Admin
System and organization knowledge collections for hybrid RAG retrieval.
Knowledge is the admin and tenant surface for retrieval-augmented generation (RAG) content used by AI chat and tools.
Knowledge is implemented end to end:
/admin/knowledge)/{orgSlug}/knowledge)knowledge-ingestion workflowsearch_knowledge_chunksautomatic, restricted, disabled) with team/user grantssystem.knowledge.manage and organization.knowledge.*source_kind).embedMany with bounded concurrency.ai_knowledge_chunks with optional halfvec(1536) embeddings and a generated tsvector for full-text search.ready. Metadata records whether embeddings succeeded (embedded, embeddingModel, embeddingTokens).Plain text families only (no PDF/DOCX/OCR in this pass):
text/plain, text/markdown, text/csv, text/html, text/xmlapplication/json, application/xml, application/yaml, application/x-yamlURL sources accept the same content types (HTML is converted to text). Oversized URL bodies (> 5 MB) fail ingestion.
| Failure | Result |
|---|---|
| Wrong embedding dimensions / model misconfiguration | File marked failed with an actionable error |
| Transient provider outage (rate limit, 5xx, network) | File marked ready as text only (metadata.embedded = false); full-text retrieval still works |
Reingest after fixing the embedding model default to backfill vectors.
Postgres stores embeddings as halfvec(1536). The default model is google/gemini-embedding-2, requested at 1536 dimensions via Matryoshka (outputDimensionality).
Only configure embedding defaults that emit exactly 1536 dimensions (or providers configured to that size). Models such as text-embedding-3-large (3072 native) are rejected at ingest time unless truncated to 1536.
search_knowledge_chunks fuses:
<=> on non-null embeddings) when a 1536-d query embedding is providedwebsearch_to_tsquery / ts_rank_cd) when a query string is providedResults are combined with reciprocal rank fusion, then filtered by:
has_knowledge_collection_accessQuery embedding failures fail open to text-only search so chat/tools keep working during provider blips.
Knowledge retrieval always runs in the caller's organization and permission context. Restricted collections require a matching team or user grant (or manage permission / creator access). Disabled collections are excluded from retrieval.