Knowledge bases (RAG)

What it does

Knowledge bases store documents (text chunks) that are retrieved and injected into the chat context when you set a bigwave_kb_id in your inference request. Operator specifies a knowledge base id (e.g. "policy-docs"), ingests documents via POST, queries them for retrieval-augmented generation (RAG), and then chat requests with that kb_id automatically include the most relevant chunks in the context window.

Prerequisites

• Documents ready to ingest (plain text, ~1000 characters per chunk recommended).
• A knowledge base id you've chosen (e.g. "faq-2024" or "legal-policies").
• Optional: test queries to verify retrieval before chatting.

Steps

1. Ingest documents

There is no UI list view for knowledge bases — operator picks a kb_id and starts ingesting immediately.

Use the API to ingest documents:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BIGWAVE_TOKEN" \
  -d '{
    "documents": [
      {
        "doc_id": "policy-001",
        "content": "Company vacation policy: 20 days per year, accrual starts on hire date."
      },
      {
        "doc_id": "policy-002",
        "content": "Remote work policy: 2 days per week on-site, flexible scheduling."
      }
    ]
  }' \
  "http://localhost:8080/admin/kb/policies/documents" | jq

The kb_id (policies in this example) is created automatically on first ingest.

2. Query the knowledge base (optional, for testing)

Before chatting with RAG, test that retrieval is working:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BIGWAVE_TOKEN" \
  -d '{
    "query": "How many vacation days do employees get?",
    "limit": 3
  }' \
  "http://localhost:8080/admin/kb/policies/query" | jq '.hits'

Returns the top limit most-relevant chunks with scores.

3. Chat with RAG enabled

Send a chat request with bigwave_kb_id in the body:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BIGWAVE_TOKEN" \
  -d '{
    "model": "qwen2.5:3b",
    "messages": [
      {"role": "user", "content": "What is the remote work policy?"}
    ],
    "bigwave_kb_id": "policies"
  }' \
  "http://localhost:8080/v1/chat/completions" | jq

The chat context is automatically augmented with the most relevant chunks from policies.

4. Verify retrieval in Observability

After a chat with RAG, open the Observability page and click the inference row. The detail drawer shows:

• Context window — a green "RAG" segment at the top showing the injected chunk.
• RAG citations — the chunk ids and scores that were retrieved.

5. (Optional) Delete a document

If you ingest a duplicate or outdated chunk:

curl -s -X DELETE \
  -H "Authorization: Bearer $BIGWAVE_TOKEN" \
  "http://localhost:8080/admin/kb/policies/documents/policy-001" | jq

Returns 204 No Content.

Verify

• Ingest documents to POST /admin/kb/{kb_id}/documents.
• Query with POST /admin/kb/{kb_id}/query and verify chunks are retrieved.
• Send a chat with bigwave_kb_id in the request body.
• Open Observability; the context window shows a green RAG segment.
• Verify the model's response references information from the ingested documents.

Common issues

Symptom	Cause	Fix
"kb_id not found" on query	Knowledge base was never created (no documents ingested)	Ingest documents first with POST /admin/kb/{kb_id}/documents
Query returns 0 hits	Documents exist but don't match the query	Ingest documents more similar to your query terms; embedding quality depends on chunk quality
Chat doesn't use RAG	bigwave_kb_id is missing from the request body or is spelled wrong	Include "bigwave_kb_id": "your-kb-id" in the POST body
"401 Unauthorized"	Bearer token is missing or invalid	cat .env | grep BIGWAVE_TOKEN and use the correct value
Ingested document doesn't appear in retrieval	Embedding failed silently or the embedding model is misconfigured	Check api container logs; try re-ingesting with different chunk boundaries

Related

• Send a chat message — chats are the user-facing interface for RAG queries.
• Inspect inferences (Observability page) — view RAG citations and the assembled context window after a RAG-enabled chat.