tencent WeKnora — retrieval & RAG queries
REQUIRED BACKGROUND: read the weknora-shared skill first (auth, --kb
resolution, the JSON envelope, exit codes, streaming/NDJSON output).
WeKnora gives you several ways to "ask about a knowledge base." Picking the wrong one wastes turns or returns the wrong shape. Use the decision table.
Pick the command by your goal
| Your goal | Command | LLM synthesis? | Returns |
|---|---|---|---|
| Natural-language answer grounded in a KB | chat "<q>" --kb <kb> |
yes | bounded answer events; --reference adds citations; --verbose adds execution detail |
| Answer via a custom agent (its own KB scope, tools, web search) | session ask --agent <id> "<q>" |
yes (+ tools) | bounded answer events; --reference adds citations; --verbose adds execution detail |
| Raw context chunks to reason over yourself (no answer) | search chunks "<q>" --kb <kb> |
no | ranked chunk list |
| Which documents match a keyword (title/filename) | search docs "<q>" --kb <kb> |
no | document list |
| Find a knowledge base by name | search kb "<q>" |
no | KB list |
| Find a past session by title | search sessions "<q>" |
no | session list |
The three decisions that matter
- Answer vs raw context. Want a written answer →
chat/session ask. Want chunks to feed into your own reasoning (e.g. you'll synthesize across sources) →search chunks. Don't callchatjust to read source text. chatvssession ask.chat= plain KB RAG Q&A.session ask --agent <id>= invoke a configured custom agent (it may scope its own KBs, call tools, do web search). If the user set up an agent for this, prefer it (weknora agent listto find ids); otherwisechat.- One-shot vs multi-turn. Both
chatandsession askreturn adata.session_idin default JSON output. Pass--session <id>on the next call to continue the conversation. In NDJSON mode, read it frominit.
Safety / Gotchas
chat,search chunks,search docsneed a KB: pass--kb <id-or-name>, or setWEKNORA_KB_ID, orweknora linkthe directory (resolved in that order). If none resolves it's exit 1 (local.kb_id_required); a bad name is exit 1 (local.kb_not_found). Resolve names withweknora kb list/search kb. (search kb/search sessionsare tenant-wide and take no--kb.)chat/session askreturn one buffered JSON envelope with answer events by default. Add--referencefor indexed citations and--verbosefor execution detail; use--format ndjsonfor raw events or--format textfor the live human-readable projection.- A stalled stream is not stopped by Ctrl-C (that just drops your local
connection; the server keeps generating + billing). Stop it server-side:
weknora session stop <session-id> --message <message-id>(session_id fromdata.session_id, or frominitunder--format ndjson). Re-attach to a stream withweknora session resume <session-id> --message <message-id>. search chunks --limitdefaults to 8 (tuned for an LLM context window); thesearch docs/kb/sessionslists default to 30. Tune retrieval with--vector-threshold/--keyword-threshold, or--no-vector/--no-keywordto disable a channel. Details:references/search-chunks.md.
Quick examples
# raw retrieval to reason over
weknora search chunks "retry backoff policy" --kb engineering --limit 12
# grounded answer (human transcript)
weknora chat "How do we handle retries?" --kb engineering --format text
# continue the conversation (session id from data.session_id above)
weknora chat "And the max attempts?" --kb engineering --session sess_abc
# answer via a custom agent
weknora session ask --agent ag_123 "Summarize this quarter's incidents"