Skip to main content

Upload Documents and Use RAG

Goal: Upload a document to the knowledge base and ask the agent questions about it.

Prerequisites: You have completed the Quickstart and the platform is running.

Time: ~5 minutes

1. Prepare a test document​

You can use any PDF, DOCX, or plain text file you already have. If you want a quick test file, create one from your terminal:

echo "AI-in-a-Box is a self-hosted sovereign AI platform. It supports multi-agent workflows, guardrails, memory, and knowledge management." > test-doc.txt

2. Upload via the UI​

Open the chat interface and click the paperclip icon. Select your file and wait for the "indexed" confirmation to appear.

Behind the scenes, the platform runs a multi-stage ingestion pipeline:

  1. The file is parsed into raw text.
  2. The text is split into chunks.
  3. Each chunk is augmented with an LLM-generated context prefix for improved retrieval accuracy.
  4. The chunks are embedded into vectors.
  5. The vectors are stored and indexed in Qdrant.

3. Ask a question about the document​

Type a question that the document can answer. For example, if you uploaded the test file above, try:

What does AI-in-a-Box support?

Watch the tool timeline on the right side of the chat. You will see the agent call knowledge_search to find relevant chunks, then compose an answer based on the retrieved content.

4. Verify the document is stored​

You can confirm the document was ingested by querying the knowledge service API directly:

curl http://localhost:8080/v1/knowledge/documents?tenant_id=default

Abbreviated response:

{
  "documents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tenant_id": "default",
      "title": "test-doc.txt",
      "filename": "test-doc.txt",
      "content_type": "text/plain",
      "chunk_count": 1,
      "ingest_status": "ready",
      "visibility_mode": "private",
      "audience_tags": [],
      "user_grants": [],
      "tags": [],
      "source_hash": "abc123...",
      "last_error": null,
      "owner_user_id": "admin",
      "creator_user_id": "admin",
      "archived_at": null,
      "created_at": "2026-04-13T10:00:00Z"
    }
  ]
}

5. Search directly via API​

You can also bypass the agent and search the knowledge base directly:

curl http://localhost:8080/v1/knowledge/search \
  -H "Content-Type: application/json" \
  -d '{"query": "sovereign AI platform", "tenant_id": "default", "limit": 3}'

Abbreviated response:

{
  "results": [
    {
      "content": "AI-in-a-Box is a self-hosted sovereign AI platform. It supports multi-agent workflows, guardrails, memory, and knowledge management.",
      "source": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "score": 0.92,
      "document_title": "test-doc.txt",
      "chunk_index": 0,
      "retrieval_rationale": "Matched chunk 0 from test-doc.txt"
    }
  ]
}

What you learned​

In this tutorial you walked through the full document ingestion and retrieval flow:

  • Document ingestion pipeline. Files are parsed, split into chunks, contextualized with LLM-generated prefixes, embedded into vectors, and indexed in Qdrant.
  • Semantic search. The knowledge service performs vector similarity search to find chunks relevant to a natural language query.
  • Agent integration. The chat agent calls the knowledge_search tool automatically when a question benefits from retrieval, combining search results with the LLM to produce grounded answers.

For the full pipeline details, wiki system, and configuration options, see the Knowledge & RAG Reference.