Knowledge Search Modes¶

This page explains how the AI uses the Knowledge Layer — the three tools it can call, the difference between the search modes, and the ACL rules that decide who sees what.

The three knowledge tools¶

knowledge_search

Returns ranked snippets from the indexed knowledge base. Each result includes the chunk text, the parent source (attachment name, model, record ID), and a relevance score.

knowledge_read

Reads the full text of one chunk or every chunk of a document. Used after knowledge_search when the AI wants the full chunk text or the whole document end-to-end.

knowledge_ask

One-shot question answering. Runs knowledge_search internally, picks the top chunks (default 5), and formats them as LLM-ready context blocks with citation numbers ([1], [2], etc.).

The tool does not generate the answer itself — answering is left to the AI client. This way:

Your Odoo doesn’t proxy to a paid LLM API.
The user’s strongest model handles the final reasoning.

Search modes¶

The mode parameter (knowledge_search) and the Engine setting (Configuration) determine how matches are scored.

`fulltext` (Basic Search)¶

PostgreSQL tsvector + trigram fuzzy.
Pure keyword match, with tolerance for typos and word stems.
Always available, no API key needed.

`vector` (Smart Search — pure semantic)¶

Cosine similarity over chunk embeddings.
Finds chunks whose meaning is closest to the query, even when no word overlaps.
Requires an embedding provider configured.

`hybrid` (Smart Search — recommended default)¶

Runs both Basic and Vector behind the scenes, then merges the rankings via Reciprocal Rank Fusion.
Gets the best of both worlds — keyword precision + semantic recall.
Requires an embedding provider configured.

Mode fallback¶

If the AI asks for hybrid or vector but no embeddings exist (provider not configured, or chunks haven’t been embedded yet), the server transparently falls back to fulltext. The response includes a mode_used field so the AI can mention this to the user.

ACL enforcement¶

Every result returned by the three tools is filtered by ir.attachment’s standard read-access rules. Concretely:

The Odoo user behind the connection must be able to read the underlying attachment.
For attachments linked to a record (the most common case), the user must be able to read the parent record.
If the user cannot read the parent record, the chunk is silently dropped — even if it matched the query strongly.

Result: the AI never returns information the user wouldn’t have been able to access by clicking around Odoo by hand.

Typical user prompts¶

“What’s our vacation policy?” → knowledge_ask searches HR attachments, formats context, AI answers with citation [1] pointing at the handbook PDF.
“What does the Acme contract say about late fees?” → knowledge_search filtered to the Acme partner’s attachments, knowledge_read for the chunk, then the AI paraphrases.
“Find me every doc that mentions GDPR.” → knowledge_search returns the matching chunks across all attachments.

Tip

For best results when uploading documents, give them a meaningful file name. The file name is the most-weighted signal in Basic Search — “Vendor Contract — Acme.pdf” beats “document_24.pdf” every time.