Knowledge / RAG search uses vector embeddings. The default embedding model is
text-embedding-3-small. Many OpenAI keys or projects do not have access to that
text-embedding-3-small
model (organization tier, model allowlist, or regional restrictions), which caused
knowledge search to silently degrade to local substring matching.
PraisonAIUI now makes this failure mode configurable and observable.
Set an accessible model via environment variable:
OPENAI_EMBEDDING_MODEL is also honoured as a fallback if AIUI_EMBEDDING_MODEL
OPENAI_EMBEDDING_MODEL
AIUI_EMBEDDING_MODEL
is not set.
The OpenAI-compatible /v1/embeddings endpoint tries the requested (or default)
/v1/embeddings
model first, then each model in the fallback chain if the primary returns a
model_not_found / 403 access error:
model_not_found
If every candidate is inaccessible, the endpoint returns 503 with an actionable
503
model_not_found error instead of a generic 500.
500
GET /api/knowledge/status reports embedding availability:
GET /api/knowledge/status
POST /api/knowledge/search indicates whether results came from vector search or a
POST /api/knowledge/search
degraded local fallback:
A dashboard can show a warning banner whenever search_mode == "fallback" or
search_mode == "fallback"
embedding.available == false.
embedding.available == false
| Model | Notes |
|-------|-------|
| text-embedding-3-small | Default — best cost/quality when available |
| text-embedding-3-large | Higher quality — may also be restricted |
text-embedding-3-large
| text-embedding-ada-002 | Legacy — widely available on older projects |
text-embedding-ada-002