RAG engine

UI

1. In the left navigation pane, select RAG Engine > Service Configuration.

2. In the Object storage (OSS) configuration panel, configure the following parameters:

   Parameter	Description	Example
   Storage type	The type of object storage service.	OSS, S3, MINIO
   Access key ID	Your access key ID.	AKxxxxxxxx
   Secret access key	Your secret access key. It is stored server-side with AES-GCM encryption. To keep a previously saved key, leave this field empty.	********
   Endpoint URL	The endpoint URL for Object Storage Service (OSS).	https://oss-cn-hangzhou.aliyuncs.com
   Region	The Object Storage Service (OSS) region.	cn-hangzhou
   Bucket	The default bucket name.	my-rag-bucket
   Prefix path	An optional path prefix for all objects stored in the bucket.	rag/
   Signature version	The signature version for authenticating requests.	s3, v4
   Addressing style	The bucket addressing style.	virtual, path

3. Click Test Connection to verify the configuration.

4. Click Save Configuration. The system then automatically restarts the RAG engine service (approx. 10-30 seconds).

API

1. Save the OSS configuration:

   POST /api/oss/config
   Content-Type: application/json
   
   {
     "storage_type":       "OSS",
     "endpoint_url":       "https://oss-cn-hangzhou.aliyuncs.com",
     "region":             "cn-hangzhou",
     "bucket":             "my-rag-bucket",
     "access_key":         "AKxxx",
     "secret_key":         "xxxxxxx",
     "prefix_path":        "rag/",
     "signature_version":  "s3",
     "addressing_style":   "virtual"
   }

2. Saving the configuration automatically restarts the RAG engine service (approx. 10-30 seconds). Once the restart is complete, call the test endpoint to verify connectivity:

   POST /api/oss/test
   Content-Type: application/json
   
   {
     "storage_type":       "OSS",
     "endpoint_url":       "https://oss-cn-hangzhou.aliyuncs.com",
     "region":             "cn-hangzhou",
     "bucket":             "my-rag-bucket",
     "access_key":         "AKxxx",
     "secret_key":         "xxxxxxx",
     "prefix_path":        "rag/",
     "signature_version":  "s3",
     "addressing_style":   "virtual"
   }

   Expected response: {"code": 0, "connected": true}.

UI

1. On the Service Configuration page, scroll to the Document engine configuration section.

2. Under Engine type at the top, select PostgreSQL or OpenSearch.

3. Switch to the corresponding tab and enter the connection parameters.

   • PostgreSQL tab

     Parameter	Default	Description
     Host / port	localhost / 5432	The instance address for PostgreSQL.
     Username / password	postgres / Leave empty if saved	Database credentials. The password is encrypted for storage.
     Database	_rag_doc_db	The name of the dedicated database for the document engine.
     Pool size / max overflow / pool timeout	20 / 10 / 30	Connection pool settings.
     Full-text search engine	gin	The engine type for full-text indexing.
     Full-text search language	chinese	The language for tokenization.
     Hybrid mode	weighted_fusion	The fusion strategy for hybrid search results.
     FTS top-N / vector top-N	100 / 100	The maximum number of results to retrieve from each retrieval path.

   • OpenSearch tab

     Parameter	Default	Description
     Host / port	opensearch / 9201	The instance address for OpenSearch.
     Username / password	admin / Leave empty if saved	Administrator credentials.

4. Click Test Connection to verify connectivity, and then click Save Configuration.

5. Under Engine type, click Switch and Restart. The system automatically restarts the RAG engine service to switch to the new engine.

API

1. Save the PostgreSQL configuration:

   POST /api/doc-engine/pg/config
   Content-Type: application/json
   
   {
     "host": "localhost",
     "port": 5432,
     "database": "_rag_doc_db",
     "username": "postgres",
     "password": "your_password"
   }

2. Test PostgreSQL connectivity (you can pass an empty body to use the saved configuration):

   POST /api/doc-engine/pg/test
   Content-Type: application/json
   
   {}

3. Switch the engine type (triggers a restart):

   POST /api/doc-engine/engine-type
   Content-Type: application/json
   
   { "engine_type": "postgresql" }

UI

1. In the left navigation pane, select RAG Engine > Model configuration.

2. Add a model provider: In the Add from preset model providers section, find your target provider (such as Tongyi, OpenAI, or DeepSeek), click Add, and enter the API key and an optional base URL.

3. Import a custom model (Optional): Click Add custom model. Fill in the model provider, model name, API key, base URL, and model type (chat, embedding, rerank, image2text). Click Validate to confirm the model is available before clicking Add.

4. Set default models: In the Tenant default models section at the top of the page, specify the following:

   • LLM: For example, qwen-plus.

   • Embedding: For example, text-embedding-v3.

   • VLM (Optional): For PDF image understanding, for example, qwen-vl-plus.

5. Click Save. The settings take effect immediately; no restart is required.

API

1. Set the API key for a model provider.

   POST /api/ragflow/llm/set_api_key
   Content-Type: application/json
   
   {
     "llm_factory": "Tongyi-Qianwen",
     "api_key":     "sk-xxxxxxxxxxxxxxxxxxxxxx",
     "base_url":    "https://dashscope.aliyuncs.com/compatible-mode/v1"
   }

   To view a list of available model providers, call GET /api/ragflow/llm/factories.

2. Set the tenant default models.

   POST /api/ragflow/set_tenant_info
   Content-Type: application/json
   
   {
     "tenant_id":  "<Get this from GET /api/ragflow/tenant_info>",
     "llm_id":     "qwen-plus@Tongyi-Qianwen",
     "embd_id":    "text-embedding-v3@Tongyi-Qianwen",
     "asr_id":     "",
     "img2txt_id": ""
   }

3. Override default models at the user level (Optional).

   PUT /api/ragflow/defaults
   Content-Type: application/json
   
   { "llm_id": "gpt-4o@OpenAI" }

Console

1. In the knowledge base list, click the folder icon for the target knowledge base to open the Document Management page.

2. Click Upload in the upper-right corner of the page. Drag and drop files into the upload box or click to select them. Supported formats include PDF, Word, Excel, PowerPoint, TXT, and Markdown.

3. Once the upload is complete, close the upload dialog. The new document appears in the document list, and its status is unprocessed.

API

curl -X POST "http://<host>/api/ragflow/datasets/<dataset_id>/documents" \
     -H "Authorization: Bearer <token>" \
     -F "file=@./product-manual.pdf" \
     -F "file=@./FAQ.md"

After you upload the documents, their status is unprocessed.

Console

1. On the Document Management page, select the documents to parse by checking them individually or using the Select All option.

2. At the top of the page, click Start Parsing.

   Note

   If no embedding model is configured, a warning appears. Click Configure to go to the knowledge base configuration page and add one.

3. During parsing, the document list automatically refreshes to show the progress. The document status changes as follows: unprocessed → parsing → completed (or failed).

API

POST /api/ragflow/datasets/<dataset_id>/documents/parse
Content-Type: application/json

{ "ids": ["doc-xxx", "doc-yyy"] }

Console

1. On the Document Management page, click the document icon for a completed document.

2. In the chunk drawer on the right, you can perform the following actions on each chunk:

   • Click Edit to manually correct errors, such as OCR mistakes or incorrect paragraph merging.

   • Use the toggle to enable or disable a chunk. Disabling a chunk temporarily excludes it from retrieval if it is low-quality.

   • Click Add Chunk to manually add content that was missed during parsing.

API

GET  /api/ragflow/datasets/<dataset_id>/documents/<doc_id>/chunks?page=1&size=20
POST /api/ragflow/datasets/<dataset_id>/documents/<doc_id>/chunks/switch

Console

1. In the navigation pane on the left, choose RAG engine > assistant.

2. Click + New assistant, and configure the following parameters:

   Basic information

   Parameter	Description
   Name	The display name of the assistant.
   Avatar	Upload a custom avatar or keep the default.
   Associated knowledge base	Select one or more knowledge bases.

   Model parameters

   Parameter	Suggested value	Description
   Model	Tenant default	The model the assistant will use. Defaults to the tenant's model, but can be overridden with a specific one.
   Temperature	0.1	A lower value makes the response adhere more strictly to the content in the knowledge base.
   Top-p	0.3	Tune either this parameter or temperature.
   Similarity threshold	0.2	Filters out retrieved chunks with a score below this threshold.
   Vector weight	0.3	In hybrid search, this is the weight of the vector similarity score.
   Top-n	6	The maximum number of chunks to pass to the LLM.
   Show citations	Enabled	Displays citations in the response that link to the original source chunks.
   Fallback response	Custom text	The response returned when no results are found in the knowledge base. This helps prevent model hallucination.

   System prompt: Configure the system prompt. Use the {{knowledge}} variable to reference the retrieved results.

3. Click Create.

API

POST /api/ragflow/chats
Content-Type: application/json

{
  "name":        "Product Support Assistant",
  "dataset_ids": ["<dataset_id>"],
  "llm":  { "temperature": 0.1, "top_p": 0.3 },
  "prompt": {
    "similarity_threshold":     0.2,
    "vector_similarity_weight": 0.3,
    "top_n":            6,
    "show_quote":       true,
    "empty_response":   "I'm sorry, but I couldn't find any relevant information in the knowledge base.",
    "prompt":           "You are a product support assistant. Answer the user's questions concisely based only on the provided {{knowledge}}."
  }
}

Console

1. In the assistant list, click an assistant's card to open the conversation view.

2. In the session list on the left, click + New conversation to start a new session, or select an existing one to continue.

3. In the input box, type your question and press Enter to send. Use Shift+Enter for a new line. The response streams in real-time.

4. At the end of each response, you can expand the citation markers to view the matched chunks and a link to the original source.

API

1. Create a session.

   POST /api/ragflow/chats/<chat_id>/sessions
   Content-Type: application/json
   
   { "name": "First conversation" }

2. Start a streaming Q&A.

   POST /api/ragflow/chats/<chat_id>/completions
   Content-Type: application/json
   
   {
     "session_id": "<session_id>",
     "question":   "How long do returns take?",
     "stream":     true
   }

   Each frame in the streaming response has the following format:

   data: {"code":0,"data":{"answer":"Typically within 7 business days...","reference":{...},"finish":false}}