mtfyun/ragflow
1
0 Fork 0
mirror of https://github.com/infiniflow/ragflow.git synced 2026-11-10 21:32:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

Doc: fix errors (#20427)

Browse Source 
Signed-off-by: Jin Hai <haijin.chn@gmail.com>
This commit is contained in:
Jin Hai authored and GitHub committed 2026-09-30 12:04:27 +08:00
1 parent 6304825676
commit 16e19da82f
17 files changed
+187 -186
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/administrator/_category_.json
+1 -1
View File
@@ -3,7 +3,7 @@
"position": 4,
"link": {
"type": "generated-index",
"description": "Guides for system administrtors"
"description": "Guides for system administrtor"
},
"customProps": {
"sidebarIcon": "LucideComputer"
docs/administrator/admin/admin_service.md
+2 -2
View File
@@ -61,7 +61,7 @@ If no superuser exists, this option currently creates `admin@ragflow.io` with th
To change the Admin listening port, set `admin.http_port` in the server configuration.
For processes on another host, set `admin.host` and `admin.http_port` in their server configuration to the reachable Admin address and port. When changing the Admin port, also update the CLI connection address and the health-check URLs below.
For processes on another host, set `admin.host` and `admin.http_port` in their server configuration to the reachable Admin address and port. When changing the Admin port, also update the CLI connection address and the health check URLs below.
## Start with Docker Compose
@@ -92,7 +92,7 @@ curl -f http://127.0.0.1:9381/healthz
The API server, ingestor, and syncer periodically send heartbeat reports to Admin. Admin keeps their latest reports in its runtime service registry; it does not register itself there. After those processes start, launch the Go CLI and log in as an administrator. If you changed the Admin port or are connecting from another host, add `--host <host:port>` to the CLI command:
```bash
./bin/ragflow-cli --admin
ragflow-cli --admin
```
```text
docs/administrator/admin/admin_ui/check_system_status.md
+10 -10
View File
@@ -18,16 +18,16 @@ For dependencies, `alive` means that the corresponding health check succeeded. `
The open-source Go deployment reports the following entries:
| Service type | Entry | How the status is determined |
| --- | --- | --- |
| `database` | MySQL | The server obtains the SQL connection and runs a database ping. |
| `doc_engine` | The configured document engine, such as Elasticsearch or Infinity | The server calls the active document engine's ping operation. |
| `storage_engine` | The configured object storage, such as MinIO | The server calls the active storage implementation's health check. |
| `cache` | Kvrocks | The server checks the configured Kvrocks connection. |
| `message_queue` | NATS | The server reads the status of the active message queue implementation. |
| `api_server` | Each reporting API process | Admin evaluates the process heartbeat. |
| `ingestor` | Each reporting Ingestor process | Admin evaluates the process heartbeat. |
| `file_syncer` | Each reporting Syncer process | Admin evaluates the process heartbeat. |
| Service type | Entry | How the status is determined |
|------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------|
| `database` | MySQL | The server obtains the SQL connection and runs a database ping. |
| `doc_engine` | The configured document engine, such as Elasticsearch or Infinity | The server calls the active document engine's ping operation. |
| `storage_engine` | The configured object storage, such as MinIO | The server calls the active storage implementation's health check. |
| `cache` | Kvrocks | The server checks the configured Kvrocks connection. |
| `message_queue` | NATS | The server reads the status of the active message queue implementation. |
| `api_server` | Each reporting API process | Admin evaluates the process heartbeat. |
| `ingestor` | Each reporting Ingestor process | Admin evaluates the process heartbeat. |
| `file_syncer` | Each reporting Syncer process | Admin evaluates the process heartbeat. |
Only processes that have reported a heartbeat to Admin appear in the process portion of the list. For dependency rows, `elapsed` records timing information from the corresponding status check; for API, Ingestor, and Syncer rows, it records the time since the latest heartbeat. The host is shown as `-` and the port as `0` when the configured document engine or storage implementation does not provide an endpoint for the status row.
docs/administrator/admin/ragflow_cli.md
+46 -46
View File
@@ -101,15 +101,15 @@ ragflow-cli --admin \
Avoid passing a real password with `--password`: command-line arguments can be visible to other local processes and may be retained in shell history. If you used the initial password, change it after logging in with `ALTER USER PASSWORD 'admin@ragflow.io' '<new_password>';`.
| Option | Description |
| --- | --- |
| `--admin`, `-admin` | Start in Admin mode. |
| `-h`, `--host <host:port>` | Admin Service address. The default is `127.0.0.1:9381`. |
| `-u`, `--user <email>` | Administrator email address. |
| Option | Description |
|-------------------------------|-------------------------------------------------------------------------------------------------------|
| `--admin`, `-admin` | Start in Admin mode. |
| `-h`, `--host <host:port>` | Admin Service address. The default is `127.0.0.1:9381`. |
| `-u`, `--user <email>` | Administrator email address. |
| `-p`, `--password <password>` | Administrator password. Prefer the interactive prompt to avoid exposing it in command-line arguments. |
| `-k`, `--key <path>` | Key file used by the client. |
| `-o`, `--output <format>` | Output format: `table`, `plain`, or `json`. |
| `-v`, `--verbose` | Enable verbose output. |
| `-k`, `--key <path>` | Key file used by the client. |
| `-o`, `--output <format>` | Output format: `table`, `plain`, or `json`. |
| `-v`, `--verbose` | Enable verbose output. |
## Commands
@@ -135,10 +135,10 @@ Logs in to the Admin Service with an administrator account. If `PASSWORD` is omi
LOGIN ADMIN '<email>' [PASSWORD '<password>'];
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<email>` | Yes | Administrator email address. |
| `[PASSWORD '<password>']` | No | Administrator password. Omit this segment to enter the password interactively. |
| Parameter | Required | Description |
|---------------------------|----------|--------------------------------------------------------------------------------|
| `<email>` | Yes | Administrator email address. |
| `[PASSWORD '<password>']` | No | Administrator password. Omit this segment to enter the password interactively. |
**Example**
@@ -260,9 +260,9 @@ Shows the current status of one service. Use the service name returned by `LIST
SHOW SERVICE '<service_name>';
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<service_name>` | Yes | Service name returned by `LIST SERVICES`, such as `mysql`. |
| Parameter | Required | Description |
|------------------|----------|------------------------------------------------------------|
| `<service_name>` | Yes | Service name returned by `LIST SERVICES`, such as `mysql`. |
**Example**
@@ -298,9 +298,9 @@ Shows details for one user.
SHOW USER '<email>';
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<email>` | Yes | User email address. |
| Parameter | Required | Description |
|-----------|----------|---------------------|
| `<email>` | Yes | User email address. |
**Example**
@@ -318,10 +318,10 @@ Creates a user with the standard `user` role.
CREATE USER '<email>' '<password>';
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<email>` | Yes | Email address for the new user. |
| `<password>` | Yes | Initial password for the new user. |
| Parameter | Required | Description |
|--------------|----------|------------------------------------|
| `<email>` | Yes | Email address for the new user. |
| `<password>` | Yes | Initial password for the new user. |
**Example**
@@ -340,10 +340,10 @@ Activates or deactivates a user.
ALTER USER ACTIVE '<email>' <on|off>;
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<email>` | Yes | User email address. |
| `<on\|off>` | Yes | `on` activates the user; `off` deactivates the user. |
| Parameter | Required | Description |
|-------------|----------|------------------------------------------------------|
| `<email>` | Yes | User email address. |
| `<on\|off>` | Yes | `on` activates the user; `off` deactivates the user. |
**Example**
@@ -362,10 +362,10 @@ Changes a user's password.
ALTER USER PASSWORD '<email>' '<new_password>';
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<email>` | Yes | User email address. |
| `<new_password>` | Yes | New password. |
| Parameter | Required | Description |
|------------------|----------|---------------------|
| `<email>` | Yes | User email address. |
| `<new_password>` | Yes | New password. |
**Example**
@@ -386,9 +386,9 @@ An active user cannot be deleted. Run `ALTER USER ACTIVE '<email>' off;` before
DROP USER '<email>';
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<email>` | Yes | Email address of a deactivated user. |
| Parameter | Required | Description |
|-----------|----------|--------------------------------------|
| `<email>` | Yes | Email address of a deactivated user. |
**Example**
@@ -411,9 +411,9 @@ Shows a runtime setting by its exact name or name prefix.
SHOW VAR '<name>';
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<name>` | Yes | Setting name or prefix, such as `mail.timeout`. |
| Parameter | Required | Description |
|-----------|----------|-------------------------------------------------|
| `<name>` | Yes | Setting name or prefix, such as `mail.timeout`. |
**Example**
@@ -535,9 +535,9 @@ Shows one API server connection from the local CLI configuration.
SHOW API SERVER '<server_name>';
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<server_name>` | Yes | Local API server configuration name, such as `default`. |
| Parameter | Required | Description |
|-----------------|----------|---------------------------------------------------------|
| `<server_name>` | Yes | Local API server configuration name, such as `default`. |
**Example**
@@ -593,9 +593,9 @@ Publishes a test message to the ingestion task subject.
MQ PUBLISH '<message>';
```
| Parameter | Required | Description |
| --- | --- | --- |
| `<message>` | Yes | String stored as the test task identifier. |
| Parameter | Required | Description |
|-------------|----------|--------------------------------------------|
| `<message>` | Yes | String stored as the test task identifier. |
**Example**
@@ -616,10 +616,10 @@ Manually pulls messages from the ingestion task consumer. The default count is `
MQ PULL [<count>] [NOACK];
```
| Parameter | Required | Description |
| --- | --- | --- |
| `[<count>]` | No | Number of messages to pull, from `1` through `100`. The default is `1`. |
| `[NOACK]` | No | Negatively acknowledges pulled messages instead of acknowledging them. |
| Parameter | Required | Description |
|-------------|----------|-------------------------------------------------------------------------|
| `[<count>]` | No | Number of messages to pull, from `1` through `100`. The default is `1`. |
| `[NOACK]` | No | Negatively acknowledges pulled messages instead of acknowledging them. |
**Example**
docs/administrator/configurations/configurations.md
+1 -1
View File
@@ -168,7 +168,7 @@ If you cannot download the RAGFlow Docker image, try the following mirrors.
- `host`: The API server's IP address inside the Docker container. Defaults to `0.0.0.0`.
- `http_port`: The API server's serving port inside the Docker container. Defaults to `9380`.
- `trusted_proxies`: The proxy IPs or CIDRs whose `X-Forwarded-For` / `X-Real-IP` headers the Go API server trusts when resolving the client address (used by the agent webhook `ip_whitelist` and login audit records). Defaults to loopback (`['127.0.0.0/8', '::1/128']`), i.e. the nginx bundled in the Docker image. An explicit list *replaces* the default rather than extending it, so keep the loopback entries when adding a further proxy placed in front of nginx, for example `['127.0.0.0/8', '::1/128', '10.0.0.0/8']`; an empty list trusts no proxy headers at all.
- `trusted_proxies`: The proxy IPs or CIDRs whose `X-Forwarded-For` / `X-Real-IP` headers the Go API server trusts when resolving the client address (used by the agent webhook `ip_whitelist` and login audit records). Defaults to loopback (`['127.0.0.0/8', '::1/128']`), i.e. the nginx bundled in the Docker image. An explicit list *replaces* the default rather than extending it, so keep the loopback entries when adding a proxy placed in front of nginx, for example `['127.0.0.0/8', '::1/128', '10.0.0.0/8']`; an empty list trusts no proxy headers at all.
### `mysql`
docs/administrator/configurations/sandbox_quickstart.md
+1 -1
View File
@@ -38,7 +38,7 @@ RAGFlow supports multiple sandbox providers. Configure the active provider in Ad
### Tenki
`tenki` runs each code execution in a fresh Tenki microVM and destroys it afterwards. It is cloud-hosted, so it needs no local sandbox services, gVisor, or Docker base images — only outbound network access and an API key.
`tenki` runs each code execution in a fresh Tenki microVM and destroys it afterward. It is cloud-hosted, so it needs no local sandbox services, gVisor, or Docker base images — only outbound network access and an API key.
Configure it in **Admin > Sandbox Settings**:
docs/administrator/migration/backup_and_migration.md
+9 -8
View File
@@ -29,14 +29,14 @@ Record the Compose project name and the volumes actually mounted by its running
The default Go stack can use these volumes, depending on the enabled services:
| Service or data | Typical volume |
| --- | --- |
| Metadata database | `<project>_mysql_data` |
| Uploaded objects in bundled MinIO | `<project>_minio_data` |
| Search index with Elasticsearch | `<project>_esdata01` |
| Go cache and persistent Redis-protocol data | `<project>_kvrocks_data` |
| NATS JetStream data | `<project>_nats_data` |
| ClickHouse analytics data | `<project>_clickhouse_data` |
| Service or data | Typical volume |
|---------------------------------------------|-----------------------------|
| Metadata database | `<project>_mysql_data` |
| Uploaded objects in bundled MinIO | `<project>_minio_data` |
| Search index with Elasticsearch | `<project>_esdata01` |
| Go cache and persistent Redis-protocol data | `<project>_kvrocks_data` |
| NATS JetStream data | `<project>_nats_data` |
| ClickHouse analytics data | `<project>_clickhouse_data` |
Also retain `docker/.env`, the configuration template, and any custom certificates or mounted files. Protect the backup because these files may contain credentials.
@@ -69,6 +69,7 @@ Keep the volume name in each archive filename and copy the entire `backup-go` di
### 3. Restore on the target host
Install the matching Go deployment and configuration on the target host. Keep services stopped and put `backup-go` in the repository root.
For each archived Docker volume, restore into a **new, empty volume**. Replace both names in this example and repeat. Keep the source name when reading the archive; use the target Compose project's name when creating its volume:
docs/administrator/migration/database_change_log.md
+50 -50
View File
@@ -29,11 +29,11 @@ Startup order in `InitDB` ([database.go](https://github.com/infiniflow/ragflow/b
## Version overview
| Database version | Scope | Gate constant |
|---|---|---|
| `v0.26.0` | Rebuild the tenant model tables from `tenant_llm` and normalize stored model ids | `modelMigrationBaseVersion` |
| `v1.0.0-rc1` | Seed factory-declared models, merge `model_type` into an integer bitmask, populate the `tenant_*_id` columns | `modelMigrationTargetVersion` |
| `v1.0.0-rc1.dev1` | Split conversation message and reference payloads into child tables | `conversationHistoryTargetVersion` |
| Database version | Scope | Gate constant |
|-------------------|--------------------------------------------------------------------------------------------------------------|------------------------------------|
| `v0.26.0` | Rebuild the tenant model tables from `tenant_llm` and normalize stored model ids | `modelMigrationBaseVersion` |
| `v1.0.0-rc1` | Seed factory-declared models, merge `model_type` into an integer bitmask, populate the `tenant_*_id` columns | `modelMigrationTargetVersion` |
| `v1.0.0-rc1.dev1` | Split conversation message and reference payloads into child tables | `conversationHistoryTargetVersion` |
The two tenant model steps are cumulative: a database at `v0.26.0` still runs the `v1.0.0-rc1` step, and a database at or above `v1.0.0-rc1` runs neither.
@@ -43,22 +43,22 @@ The two tenant model steps are cumulative: a database at `v0.26.0` still runs th
### Schema changes
| Object | Change |
|---|---|
| `system_settings` | Created if missing, so the version marker can be written before `AutoMigrate` reaches the table. |
| Object | Change |
|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `system_settings` | Created if missing, so the version marker can be written before `AutoMigrate` reaches the table. |
| `tenant_model_provider` | Created if missing. Columns: `id` (PK, varchar 32), `provider_name`, `tenant_id`, base timestamps. Unique index `idx_tenant_provider_unique (tenant_id, provider_name)`. |
| `tenant_model_instance` | Created if missing. Columns: `id` (PK), `instance_name`, `provider_id`, `api_key`, `status`, `extra`, base timestamps. |
| `tenant_model` | Created if missing. Columns: `id` (PK), `model_name`, `provider_id`, `instance_id`, `model_type`, `status`, `extra`, base timestamps. |
| `tenant_model_instance` | Created if missing. Columns: `id` (PK), `instance_name`, `provider_id`, `api_key`, `status`, `extra`, base timestamps. |
| `tenant_model` | Created if missing. Columns: `id` (PK), `model_name`, `provider_id`, `instance_id`, `model_type`, `status`, `extra`, base timestamps. |
The three tables are created only when the legacy `tenant_llm` table exists and the target table does not, mirroring the `CREATE TABLE IF NOT EXISTS` the Python stages run. Existing tables are never altered by this step: `tenant_model.model_type` deliberately keeps the text shape the Python migration left behind so the `v1.0.0-rc1` merge can still read the legacy model names.
### Data migration
| Table | Change |
|---|---|
| `tenant_model_provider` | One row per distinct `(tenant_id, llm_factory)` in `tenant_llm`; `provider_name` takes the factory name. |
| `tenant_model_instance` | One row per `(tenant_id, llm_factory)`, carrying the first `api_key` after deduplication; `instance_name` defaults to `default`. |
| `tenant_model` | Rows derived from `tenant_llm`: `model_type` is written as an integer bitmask, only groups whose merged status is `active` are kept, and `provider_id` / `instance_id` point at the rows created above. Bits: `chat=1`, `embedding=2`, `asr`/`speech2text=4`, `vision`/`image2text=8`, `rerank=16`, `tts=32`, `ocr=64`. |
| Table | Change |
|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `tenant_model_provider` | One row per distinct `(tenant_id, llm_factory)` in `tenant_llm`; `provider_name` takes the factory name. |
| `tenant_model_instance` | One row per `(tenant_id, llm_factory)`, carrying the first `api_key` after deduplication; `instance_name` defaults to `default`. |
| `tenant_model` | Rows derived from `tenant_llm`: `model_type` is written as an integer bitmask, only groups whose merged status is `active` are kept, and `provider_id` / `instance_id` point at the rows created above. Bits: `chat=1`, `embedding=2`, `asr`/`speech2text=4`, `vision`/`image2text=8`, `rerank=16`, `tts=32`, `ocr=64`. |
| `tenant`, `knowledgebase`, `dialog`, `memory` | Stored model ids are rewritten from `<model>@<provider>` to `<model>@default@<provider>`: `tenant.llm_id / embd_id / asr_id / img2txt_id / rerank_id / tts_id / ocr_id`, `knowledgebase.embd_id`, `dialog.llm_id / rerank_id`, `memory.embd_id / llm_id`, plus the same keys nested inside `parser_config` and `prompt_config` JSON (`llm_id`, `embd_id`, `embedding_model`, `rerank_id`, `asr_id`, `img2txt_id`, `tts_id`, `ocr_id`). |
On success the step writes `v0.26.0` into the version marker.
@@ -69,22 +69,22 @@ On success the step writes `v0.26.0` into the version marker.
### Schema changes
| Table | Change |
|---|---|
| `tenant_model` | `model_type` is converted from the legacy text representation to the integer bitmask (see the data migration below). Once the column is an integer the conversion is a no-op. |
| `tenant` | Adds `tenant_llm_id`, `tenant_embd_id`, `tenant_asr_id`, `tenant_img2txt_id`, `tenant_rerank_id`, `tenant_tts_id`, `tenant_ocr_id` — each `varchar(32) NULL`. |
| `knowledgebase` | Adds `tenant_embd_id` — `varchar(32) NULL`. |
| `dialog` | Adds `tenant_llm_id`, `tenant_rerank_id` — `varchar(32) NULL`. |
| `memory` | Adds `tenant_embd_id`, `tenant_llm_id` — `varchar(32) NULL`. |
| Table | Change |
|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `tenant_model` | `model_type` is converted from the legacy text representation to the integer bitmask (see the data migration below). Once the column is an integer the conversion is a no-op. |
| `tenant` | Adds `tenant_llm_id`, `tenant_embd_id`, `tenant_asr_id`, `tenant_img2txt_id`, `tenant_rerank_id`, `tenant_tts_id`, `tenant_ocr_id` — each `varchar(32) NULL`. |
| `knowledgebase` | Adds `tenant_embd_id` — `varchar(32) NULL`. |
| `dialog` | Adds `tenant_llm_id`, `tenant_rerank_id` — `varchar(32) NULL`. |
| `memory` | Adds `tenant_embd_id`, `tenant_llm_id` — `varchar(32) NULL`. |
The `tenant_*_id` columns are added only when missing, and are skipped entirely when any of `tenant_model`, `tenant_model_provider`, `tenant_model_instance` is absent.
### Data migration
| Table | Change |
|---|---|
| `tenant_model` | **Seeding:** the models declared in `conf/llm_factories.json` are inserted for every provider/instance created by the `v0.26.0` step. When a `(provider_id, instance_id, model_name)` row already exists, the declared factory bits are OR-ed into its `model_type` instead of a second row being inserted. |
| `tenant_model` | **Type merge:** rows sharing `(provider_id, instance_id, model_name)` collapse into a single row whose `model_type` is the OR of the contributing bits. Bits that only ever appeared on `unsupported` rows are dropped, and groups whose merged status is not `active` are dropped. |
| Table | Change |
|-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `tenant_model` | **Seeding:** the models declared in `conf/llm_factories.json` are inserted for every provider/instance created by the `v0.26.0` step. When a `(provider_id, instance_id, model_name)` row already exists, the declared factory bits are OR-ed into its `model_type` instead of a second row being inserted. |
| `tenant_model` | **Type merge:** rows sharing `(provider_id, instance_id, model_name)` collapse into a single row whose `model_type` is the OR of the contributing bits. Bits that only ever appeared on `unsupported` rows are dropped, and groups whose merged status is not `active` are dropped. |
| `tenant`, `knowledgebase`, `dialog`, `memory` | **Id backfill:** each `tenant_*_id` column is filled from its legacy counterpart (`llm_id`, `embd_id`, …) by resolving the referenced `tenant_model.id` through a `(tenant_id, model_name, provider, model_type)` lookup over active models, with the `model_type` bitmask expanded back into individual types. |
On success the step writes `v0.27.2` into the version marker.
@@ -97,19 +97,19 @@ This step only prepares the schema owned by `v1.0.0-rc1`; dropping the legacy pa
### Schema changes
| Table | Change |
|---|---|
| `conversation_message` | Created by `AutoMigrate`. Composite PK `(conversation_id, position)`; columns `message_id`, `role`, `content`, `content_type`, `status`, `thumb_up`, `feedback`, `created_at`, `metadata`; composite index `message_lookup (conversation_id, message_id, role, position)`; foreign key `conversation_id → conversation.id` with `ON DELETE CASCADE`. |
| `conversation_reference` | Created by `AutoMigrate`. Composite PK `(conversation_id, position)`; columns `reference` (longtext), `message_position`; foreign key `conversation_id → conversation.id` with `ON DELETE CASCADE`. |
| `api_4_conversation_message` | Same shape as `conversation_message`, parented by `api_4_conversation`. |
| `api_4_conversation_reference` | Same shape as `conversation_reference`, parented by `api_4_conversation`. |
| `conversation`, `api_4_conversation` | Unchanged by this step: the legacy `message` and `reference` payload columns stay in place. The Go schema marks both `gorm:"-"`, so only a probe model can still read them. |
| Table | Change |
|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `conversation_message` | Created by `AutoMigrate`. Composite PK `(conversation_id, position)`; columns `message_id`, `role`, `content`, `content_type`, `status`, `thumb_up`, `feedback`, `created_at`, `metadata`; composite index `message_lookup (conversation_id, message_id, role, position)`; foreign key `conversation_id → conversation.id` with `ON DELETE CASCADE`. |
| `conversation_reference` | Created by `AutoMigrate`. Composite PK `(conversation_id, position)`; columns `reference` (longtext), `message_position`; foreign key `conversation_id → conversation.id` with `ON DELETE CASCADE`. |
| `api_4_conversation_message` | Same shape as `conversation_message`, parented by `api_4_conversation`. |
| `api_4_conversation_reference` | Same shape as `conversation_reference`, parented by `api_4_conversation`. |
| `conversation`, `api_4_conversation` | Unchanged by this step: the legacy `message` and `reference` payload columns stay in place. The Go schema marks both `gorm:"-"`, so only a probe model can still read them. |
### Data migration
| Table | Change |
|---|---|
| `conversation_message`, `api_4_conversation_message` | Each element of the parent row's `message` JSON array becomes one row, `position` being its index in the array. |
| Table | Change |
|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `conversation_message`, `api_4_conversation_message` | Each element of the parent row's `message` JSON array becomes one row, `position` being its index in the array. |
| `conversation_reference`, `api_4_conversation_reference` | Each entry of the parent row's `reference` JSON array becomes one row, `position` being its index in the array. `message_position` stays `NULL`: the payload carries no message binding, and only references written together with a message by the current code path set it. |
Execution details:
@@ -128,22 +128,22 @@ These steps are not gated by the version marker. They are idempotent and run on
### Schema changes
| Table | Change |
|---|---|
| `tenant_llm` | Composite primary key `(tenant_id, llm_factory, llm_name)` is replaced by a surrogate auto-increment `id`; the legacy uniqueness is preserved by a unique index on the old key columns. |
| `task`, `document` | `process_duation` renamed to `process_duration`. |
| `user` | Unique index on `email`. |
| `ingestion_task` | Unique index on `document_id`. |
| `knowledgebase` | Adds the `VIRTUAL` generated column `name_ci` (`LOWER(name)` for `status='1'` rows, `NULL` otherwise) and the unique index `idx_kb_tenant_name_ci (tenant_id, name_ci)`, so soft-deleted rows never block name reuse. |
| `user_canvas` | Unique index `(user_id, canvas_category, title)`. |
| `pipeline_operation_log` | Adds `run_count int NULL` and the index `idx_pipeline_operation_log_document_run`. |
| `ingestion_task` | Adds `pipeline_log_id varchar(32) NULL`. |
| `ingestion_task_log` | Adds `pipeline_log_id varchar(32) NULL`, `event_type tinyint NOT NULL DEFAULT 4`, and the index `idx_ingestion_task_log_pipeline_id`. |
| Table | Change |
|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `tenant_llm` | Composite primary key `(tenant_id, llm_factory, llm_name)` is replaced by a surrogate auto-increment `id`; the legacy uniqueness is preserved by a unique index on the old key columns. |
| `task`, `document` | `process_duation` renamed to `process_duration`. |
| `user` | Unique index on `email`. |
| `ingestion_task` | Unique index on `document_id`. |
| `knowledgebase` | Adds the `VIRTUAL` generated column `name_ci` (`LOWER(name)` for `status='1'` rows, `NULL` otherwise) and the unique index `idx_kb_tenant_name_ci (tenant_id, name_ci)`, so soft-deleted rows never block name reuse. |
| `user_canvas` | Unique index `(user_id, canvas_category, title)`. |
| `pipeline_operation_log` | Adds `run_count int NULL` and the index `idx_pipeline_operation_log_document_run`. |
| `ingestion_task` | Adds `pipeline_log_id varchar(32) NULL`. |
| `ingestion_task_log` | Adds `pipeline_log_id varchar(32) NULL`, `event_type tinyint NOT NULL DEFAULT 4`, and the index `idx_ingestion_task_log_pipeline_id`. |
| `dialog`, `tenant_llm`, `api_token`, `canvas_template`, `system_settings`, `knowledgebase` | Column types converged to the Peewee models, for example `dialog.top_k int NOT NULL DEFAULT 1024`, `tenant_llm.api_key text`, `api_token.dialog_id varchar(32)`, `canvas_template.title` / `description` nullable longtext, `system_settings.value text NOT NULL`, `knowledgebase.raptor_task_finish_at` / `mindmap_task_finish_at` datetime. |
| `conversation`, `api_4_conversation` | Index `idx_<table>_dialog_updated (dialog_id, update_time, id)` for conversation list queries. |
| `conversation`, `api_4_conversation` | Index `idx_<table>_dialog_updated (dialog_id, update_time, id)` for conversation list queries. |
### Data changes
| Table | Change |
|---|---|
| Table | Change |
|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `knowledgebase`, `dialog` | `parser_config` entries stored under the legacy key `TokenChunker:SixApplesFall` are rewritten to `GeneralChunker:SixApplesFall`. Values already stored under the new key win; `TokenChunker`-only fields (`delimiter_mode`, `outputs`) are dropped, and a legacy `delimiter` becomes `delimiters`. `delimiter` is discarded when `delimiters` already exists. |
docs/basics/agent_context_engine.md
+5 -5
View File
@@ -47,11 +47,11 @@ The necessity of an Agent Context Engine becomes clear when we examine the alter
The shift from Context Engineering to a Context Platform/Engine marks the maturation of enterprise AI, as summarized in the table below:
| Dimension | Context engineering (present) | Context engineering/Platform (future) |
| ------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Context creation | Manual, artisanal work by developers and prompt engineers. | Automated, driven by intelligent ingestion pipelines and configurable rules. |
| Context delivery | Hard-coded prompts and static retrieval logic embedded in agent workflows. | Dynamic, real-time retrieval and assembly based on the agent's live state and intent. |
| Context maintenance | A development and operational burden, logic locked in code. | A manageable platform function, with visibility and control returned to the business. |
| Dimension | Context engineering (present) | Context engineering/Platform (future) |
|---------------------|----------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| Context creation | Manual, artisanal work by developers and prompt engineers. | Automated, driven by intelligent ingestion pipelines and configurable rules. |
| Context delivery | Hard-coded prompts and static retrieval logic embedded in agent workflows. | Dynamic, real-time retrieval and assembly based on the agent's live state and intent. |
| Context maintenance | A development and operational burden, logic locked in code. | A manageable platform function, with visibility and control returned to the business. |
## RAGFlow: A Resolute March Toward the Context Engine of Agents
docs/develop/mcp/connect_an_external_mcp_to_ragflow.md
+13 -13
View File
@@ -45,12 +45,12 @@ RAGFlow does not directly connect to MCP servers that use `stdio`. To use a `std
6. Click the refresh button in **Tools available** to test the connection and discover tools.
7. After the test succeeds and the discovered tools appear, click **Save**.
| Field | Description | Example |
| --- | --- | --- |
| Name | A name containing letters, numbers, underscores, or hyphens (up to 64 characters) | `web_search_tools` |
| URL | The complete MCP endpoint | `https://example.com/mcp` |
| Server type | The transport provided by the MCP server | `streamable-http` |
| Authorization Token | Optional token sent as `Authorization: Bearer <token>` | The server's token |
| Field | Description | Example |
|---------------------|-----------------------------------------------------------------------------------|---------------------------|
| Name | A name containing letters, numbers, underscores, or hyphens (up to 64 characters) | `web_search_tools` |
| URL | The complete MCP endpoint | `https://example.com/mcp` |
| Server type | The transport provided by the MCP server | `streamable-http` |
| Authorization Token | Optional token sent as `Authorization: Bearer <token>` | The server's token |
The **Server type** must match the transport exposed by the MCP server:
@@ -82,13 +82,13 @@ Consequently, endpoints such as `localhost`, `127.0.0.1`, `::1`, `10.x.x.x`, `17
## Troubleshoot a failed connection
| Symptom | What to check |
| --- | --- |
| `Invalid MCP url` or a disallowed-scheme error | Use a complete `http://` or `https://` endpoint with the correct `/mcp` or `/sse` path. |
| `URL resolves to a non-public address` | Check DNS from the RAGFlow backend environment. Public hostnames are also rejected if any result is private or synthetic. Proxy tools in Fake-IP mode can cause this result. |
| Connection or discovery timeout | Check outbound network access, the selected transport, endpoint path, and server availability. The default discovery timeout is 10 seconds. |
| Authentication failure | Verify the token, or import string-valued custom headers when the server does not use a Bearer token. |
| Save remains disabled | Test the current settings again and confirm that the server advertises at least one tool. |
| Symptom | What to check |
|------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Invalid MCP url` or a disallowed-scheme error | Use a complete `http://` or `https://` endpoint with the correct `/mcp` or `/sse` path. |
| `URL resolves to a non-public address` | Check DNS from the RAGFlow backend environment. Public hostnames are also rejected if any result is private or synthetic. Proxy tools in Fake-IP mode can cause this result. |
| Connection or discovery timeout | Check outbound network access, the selected transport, endpoint path, and server availability. The default discovery timeout is 10 seconds. |
| Authentication failure | Verify the token, or import string-valued custom headers when the server does not use a Bearer token. |
| Save remains disabled | Test the current settings again and confirm that the server advertises at least one tool. |
## Example: add Parallel Search MCP tools
docs/guides/agent/agent_workflow/tool_components.md
+33 -33
View File
@@ -630,45 +630,45 @@ The Document Generator component outputs Markdown content as PDF, DOCX, TXT, Mar
#### Parameter Description
| Field | Type | Required | Default Value | Description |
| --- | --- | --- | --- | --- |
| content | string | Yes | Empty | Markdown content to generate. Upstream outputs can be referenced. |
| output_format | string | Yes | pdf | Output format: `pdf`, `docx`, `txt`, `markdown`, or `html`. |
| filename | string | No | Empty | File name. If empty, it is generated automatically, and illegal file name characters are cleaned. |
| header_text | string | No | Empty | Header text. Applies to PDF/DOCX. |
| footer_text | string | No | Empty | Footer text. Applies to PDF/DOCX. |
| watermark_text | string | No | Empty | Watermark text. Supported by PDF/DOCX/HTML according to the implementation. |
| add_page_numbers | boolean | No | true | Whether to add page numbers. Mainly used for PDF/DOCX. |
| add_timestamp | boolean | No | true | Whether to add generation time. |
| include_download_info_in_content | boolean | No | false | Whether to keep the download information marker in the content. |
| font_size | number | No | 12 | Font size, which must be greater than or equal to 12. |
| Field | Type | Required | Default Value | Description |
|----------------------------------|---------|----------|---------------|---------------------------------------------------------------------------------------------------|
| content | string | Yes | Empty | Markdown content to generate. Upstream outputs can be referenced. |
| output_format | string | Yes | pdf | Output format: `pdf`, `docx`, `txt`, `markdown`, or `html`. |
| filename | string | No | Empty | File name. If empty, it is generated automatically, and illegal file name characters are cleaned. |
| header_text | string | No | Empty | Header text. Applies to PDF/DOCX. |
| footer_text | string | No | Empty | Footer text. Applies to PDF/DOCX. |
| watermark_text | string | No | Empty | Watermark text. Supported by PDF/DOCX/HTML according to the implementation. |
| add_page_numbers | boolean | No | true | Whether to add page numbers. Mainly used for PDF/DOCX. |
| add_timestamp | boolean | No | true | Whether to add generation time. |
| include_download_info_in_content | boolean | No | false | Whether to keep the download information marker in the content. |
| font_size | number | No | 12 | Font size, which must be greater than or equal to 12. |
#### Supported Values
| Parameter | Supported Value | Description |
| --- | --- | --- |
| Output Format | pdf | PDF document. |
| Output Format | docx | Word document. |
| Output Format | html | HTML document. |
| Output Format | txt | Text file. |
| Output Format | markdown | Markdown file. |
| Font Size | >=12 | Font size must be greater than or equal to 12. |
| Parameter | Supported Value | Description |
|---------------|-----------------|------------------------------------------------|
| Output Format | pdf | PDF document. |
| Output Format | docx | Word document. |
| Output Format | html | HTML document. |
| Output Format | txt | Text file. |
| Output Format | markdown | Markdown file. |
| Font Size | >=12 | Font size must be greater than or equal to 12. |
#### Configuration Example
| Configuration Item | Example Value |
| --- | --- |
| Content | `# RAGFlow Agent
Test This document is generated by the DocGenerator component.` |
| Output Format | pdf |
| Filename | ragflow-agent-test.pdf |
| Header Text | RAGFlow |
| Footer Text | Internal Test |
| Watermark Text | DRAFT |
| Add Page Numbers | true |
| Add Timestamp | true |
| Include Download Info In Content | false |
| Font Size | 12 |
| Configuration Item | Example Value |
|-----------------------------------------------------------------|------------------------|
| Content | `# RAGFlow Agent |
| Test This document is generated by the DocGenerator component.` | |
| Output Format | pdf |
| Filename | ragflow-agent-test.pdf |
| Header Text | RAGFlow |
| Footer Text | Internal Test |
| Watermark Text | DRAFT |
| Add Page Numbers | true |
| Add Timestamp | true |
| Include Download Info In Content | false |
| Font Size | 12 |
#### Output Result
docs/guides/agent/ingestion_pipeline/create_ingestion_pipeline.md
+1 -1
View File
@@ -14,4 +14,4 @@ sidebar_custom_props: {
2. Click **Create Agent** and start from a blank canvas or a prebuilt template. Templates are recommended for beginners.
![Create an Ingestion Pipeline](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/create_an_ingestion_pipeline.jpg)
3. On the canvas, drag, drop and connect components from the right panel to design your flow, for example: Parser -> Chunker -> Transformer -> Indexer.
3. On the canvas, drag, drop and connect components from the right panel to design your flow, for example: Parser → Chunker → Transformer → Indexer.
docs/guides/dataset/configuration.md
+4 -4
View File
@@ -369,10 +369,10 @@ Users can assign one of the following roles to each column through the drop-down
For example, if a table contains four columns, **Title**, **Content**, **Category**, and **Year**, you can set them according to actual use:
- **Title -> Both**: The title participates in retrieval and can also be used as metadata.
- **Content -> Indexing**: The body text is mainly used for content retrieval.
- **Category -> Metadata**: Used to filter retrieval results by category.
- **Year -> Metadata**: Used to filter retrieval results by year.
- **Title → Both**: The title participates in retrieval and can also be used as metadata.
- **Content → Indexing**: The body text is mainly used for content retrieval.
- **Category → Metadata**: Used to filter retrieval results by category.
- **Year → Metadata**: Used to filter retrieval results by year.
In this way, fields that do not need to participate in content retrieval can be prevented from entering chunk text, while these fields are still preserved as retrieval filter conditions.
docs/guides/dataset/retrieval_testing.md
+1 -1
View File
@@ -63,4 +63,4 @@ If the target chunk can be recalled but many irrelevant results also appear, rai
If you need to see more or fewer candidate results, adjust **Top**. For cross-language datasets, also check whether **Cross-language search** includes the target languages to retrieve. It is recommended to use multiple representative queries for repeated testing and determine final parameters based on the overall recall result instead of adjusting configuration based only on a single test.
Debugging suggestion: when retrieval results are unsatisfactory, troubleshoot in the order of document parsing -> chunk -> metadata -> retrieval parameters. First confirm that the knowledge content itself has correctly entered the dataset, then adjust retrieval parameters. This helps locate the problem faster.
Debugging suggestion: when retrieval results are unsatisfactory, troubleshoot in the order of document parsing → chunk → metadata → retrieval parameters. First confirm that the knowledge content itself has correctly entered the dataset, then adjust retrieval parameters. This helps locate the problem faster.
docs/guides/knowledge_compilation/built_in_templates_and_dedicated_configuration.md
+8 -8
View File
@@ -292,16 +292,16 @@ Relationship configuration parameters:
The system provides the following default relationship types:
| Relationship Name | Description |
| --- | --- |
| has_branch | Indicates that the core topic contains major branches and is used to connect CentralTopic and Branch. |
| has_sub_branch | Indicates that a branch contains more specific sub-branches and is used to connect Branch and Sub-branch. |
| supports | Indicates that keywords, cases, or details provide supplementary explanation for an upper-level concept. |
| related_to | Indicates an association between two concepts that does not belong to a clear parent-child structure. |
| Relationship Name | Description |
|-------------------|-----------------------------------------------------------------------------------------------------------|
| has_branch | Indicates that the core topic contains major branches and is used to connect CentralTopic and Branch. |
| has_sub_branch | Indicates that a branch contains more specific sub-branches and is used to connect Branch and Sub-branch. |
| supports | Indicates that keywords, cases, or details provide supplementary explanation for an upper-level concept. |
| related_to | Indicates an association between two concepts that does not belong to a clear parent-child structure. |
Users can adjust relationship definitions based on document content characteristics:
- For content with a clear hierarchy, use inclusion relationships such as topic -> branch -> sub-branch.
- For content with a clear hierarchy, use inclusion relationships such as topic → branch → sub-branch.
- For content with associations but no parent-child relationship, use association relationships.
- Relationship names should be concise and clear, and should reflect the connection meaning between nodes.
- Avoid configuring too many meaningless relationships to prevent generating a complex or hard-to-understand mind map structure.
@@ -521,7 +521,7 @@ The system provides the following blueprints:
- **General**: A general blueprint suitable for documents without specific content structure requirements.
- **Market**: Suitable for market, industry analysis, and related content.
- **Product**: Suitable for product introductions, product planning, and product-related documents.
- **Userinterview**: Suitable for user interviews, research records, and similar content.
- **Interview**: Suitable for user interviews, research records, and similar content.
- **Custom**: A custom blueprint that can configure Wiki page generation rules based on actual requirements.
| Configuration Item | Description |
docs/references/glossary.mdx
+1 -1
View File
@@ -415,7 +415,7 @@ Candidate chunks with relevance scores below this threshold are filtered out. In
**Skills**
Skills are a knowledge organization mechanism that precompiles knowledge from a knowledge base into a navigable hierarchical directory.
Skills are a knowledge organization mechanism that precompiled knowledge from a knowledge base into a navigable hierarchical directory.
They organize knowledge into a hierarchical structure based on thematic and semantic relationships, with directory summaries describing the knowledge contained at each level and its child branches. During retrieval, an Agent reads these summaries based on the user query, selects relevant branches, and progressively navigates down the hierarchy to locate and retrieve the relevant source documents or evidence.
docs/release_notes.md
+1 -1
View File
@@ -956,7 +956,7 @@ Released on May 26, 2025.
> The following features have been contributed by our community:
- Agent component: Enables tool calling within the Generate Component. Thanks to [notsyncing](https://github.com/notsyncing).
- Markdown rendering: Image references in a markdown file can be displayed after chunking. Thanks to [Woody-Hu](https://github.com/Woody-Hu).
- Markdown rendering: Image references in a Markdown file can be displayed after chunking. Thanks to [Woody-Hu](https://github.com/Woody-Hu).
- Document engine support: OpenSearch can now be used as RAGFlow's document engine. Thanks to [pyyuhao](https://github.com/pyyuhao).
### Documentation