Getting started
Your first knowledge base
Create a local identity, configure models, import a document, and get a cited answer.This page starts with a new SAG instance and walks through identity, model configuration, a source, a document, and the first cited answer. The workflow is the same in Docker and the desktop application.
1. Create a local identity
Enter your name the first time SAG opens. The system creates or restores a single-user identity on this machine and uses its JWT for subsequent API requests.
This local identity is not a public cloud account. The default deployment has no third-party sign-in and does not upload your knowledge to a service operated by the SAG project.
2. Configure models
Open Settings -> Models. SAG needs two kinds of model capability:
| Capability | Used for | Does it block startup? |
|---|---|---|
| LLM | Event extraction, query understanding, precise-retrieval reranking, and answer generation | The interface still starts without it |
| Embedding | Document vectorization and vector retrieval | Documents cannot complete a searchable index without it |
You can use 302.AI for quick configuration or enter any OpenAI-compatible endpoint. If the same service provides both Embedding and LLM models, the Embedding key and base URL can reuse the LLM settings.
Run the connection test before saving. Model names must be identifiers that the server actually supports; example defaults do not imply that every compatible service offers models with those names.
3. Create a source
Open Knowledge Base and create a source. A source is the logical boundary for documents, indexes, graphs, and access scope. One DataEngine instance also corresponds to one logical source.
Use a name that describes the content, such as "Product documentation," "Research papers," or "Customer support handbook." Avoid names such as "Test 1" that become difficult to identify later.
4. Import a document
Open the source and upload Markdown, text, PDF, or an Office document. SAG advances through these states:
uploaded -> parsing -> chunking and embedding -> event/entity extraction -> readyOnly documents in the ready state participate reliably in retrieval. Large files and remote parsers can keep background jobs running longer. Progress and errors remain visible in the document list.
5. Retrieve and inspect the source
Open Search, select fast mode, and ask a question whose answer definitely exists in the document. Open "View source" on a result and verify that the displayed text supports the query.
If the results are too broad, restrict retrieval to the source you just created. If the question requires relationships across passages, switch to precise mode.
6. Get a cited answer
Create a conversation, use @ to select the knowledge source, and ask the same question. When the answer completes, verify that:
- the answer contains clickable citations;
- each citation opens a specific source chunk;
- the cited text directly supports the important claims in the answer.
Completion criteria
Your first knowledge base is ready when all four conditions hold:
- the document state is ready;
- fast retrieval returns relevant content;
- a result opens its source text;
- a conversation answer contains verifiable citations.
Continue with Ingestion and parsing, or expose the same knowledge base to an external Agent through MCP.