diff --git a/AGENTS.md b/AGENTS.md index e506e490d3..c30473070c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,19 +11,26 @@ Use this file as the local operating guide for the current codebase. Prefer the - Keep refactors centered on the owning abstraction, not on adjacent compatibility layers. ## Current stack -- Backend: Python 3.13+, Quart-based API server, Peewee ORM, async workers. -- Frontend: React + TypeScript + Vite in `web/`. When working under `web/`, read and follow `web/AGENTS.md` — it holds the frontend conventions (dual-backend Go/Python variants, test placement, styling, data fetching). -- Go: the repository also has a substantial Go module for servers, ingestion, parser/runtime, CLI, and supporting services. -- Runtime services commonly include MySQL/PostgreSQL, Redis, MinIO, and Elasticsearch/Infinity/OpenSearch depending on configuration. +- Backend: Go implements the API, admin, ingestor, and syncer modes in `cmd/ragflow_server.go`; the CLI runs from `cmd/ragflow-cli.go`. The Python API, admin, and workers are still present and `docker/entrypoint.sh` still defaults to Python when `API_PROXY_SCHEME` is unset. Go-only operation is the migration target, not the current repository state. +- Frontend: React + TypeScript + Vite in `web/`. When working under `web/`, read and follow `web/AGENTS.md` for frontend conventions. +- The Go module contains the server, ingestion, parsing, agent runtime, CLI, and supporting services. +- Runtime services commonly include MySQL/PostgreSQL, Kvrocks, NATS JetStream, MinIO, ClickHouse, and Elasticsearch/Infinity/OpenSearch depending on configuration. +## Go-only target +- Remove all Python code and Python-specific dependencies, scripts, containers, CI jobs, documentation, SDKs, and tests from the repository. Do not add new Python code while this removal is in progress. Replace Python-based preparation of Go native libraries, DeepDoc models, and the BPE table before removing the existing download scripts. +- Move any still-required behavior and test coverage into the Go backend or the frontend before deleting the old implementation. Do not preserve a Python server, compatibility layer, fallback, or dual-backend path. +- Before deleting `rag/`, move the Go DeepDoc `.ort` models and `ocr.res` out of `rag/res/deepdoc/`, then update model discovery, dependency preparation, Docker packaging, and tests together. +- Remove the frontend's Go/Python backend variants and update `web/CLAUDE.md` when the frontend no longer needs them. Until then, treat its dual-backend instructions as migration-only guidance; new frontend work should target the Go API. +- Update Docker's default entrypoint, dependency image, and CI workflows when removing their Python paths. Until then, select Go explicitly with `API_PROXY_SCHEME=go` where that variable controls startup. +- Keep this guide aligned with the checked-in tree. Once the Python directories are deleted, remove their migration inventory below. ## Code Layout to Expect -- `api/`: Python API server entrypoints, blueprints, services, and database code. -- `rag/`: ingestion, retrieval, LLM integration, and graph RAG logic. -- `deepdoc/`: parsing and OCR. -- `agent/`: workflow canvas, components, tools, and templates. -- `cmd/`: Go entrypoints. `ragflow_main` is the main server/admin/ingestor binary surface; `ragflow-cli` is the CLI entrypoint. +- `cmd/ragflow_server.go`: Go entrypoint for the API, admin, ingestor, and syncer modes (`--api`, `--admin`, `--ingestor`, `--syncer`). +- `cmd/ragflow-cli.go`: Go CLI entrypoint. +- `api/`, `rag/`, `deepdoc/`, and `agent/`: legacy Python implementation pending deletion. Do not add features or extend dependencies there. - `internal/`: main Go application code. Important subtrees: - `internal/agent/`: Go agent runtime, canvas execution, components, tool bindings, workflow helpers. +- `internal/admin/`: Go admin routes, handlers, and services. +- `internal/binding/cpp/`: C++ tokenizer binding built by `build.sh` for the Go server. - `internal/cli/`: CLI parsing, HTTP transport, command execution, response formatting. - `internal/dao/`: Go data-access layer and persistence-facing helpers. - `internal/deepdoc/`: Go DeepDOC integrations, especially native-backed PDF/DOCX parsing. @@ -40,10 +47,14 @@ Use this file as the local operating guide for the current codebase. Prefer the - `internal/storage/`: storage backends and in-memory test doubles. - `internal/router/`: HTTP route registration. - `internal/server/`: server bootstrap/config wiring. -- `internal/cpp/`: C++ sources used by native-backed Go features. +- `internal/syncer/`: Go file synchronization service and connectors. +- `internal/rag/`: Go retrieval and RAG logic. +- `internal/harness/`: Go runtime harness and supporting execution code. - `web/`: frontend application. - `docker/`: local and production compose files. -- `sdk/` and `test/`: SDK and automated tests. +- `sdk/python/`: legacy Python client SDK pending deletion. +- `ragflow_deps/download_go_deps.py`: current Python helper for Go native libraries and model files; replace it before deleting it. `build.sh` currently reads its ONNX Runtime version pin. +- `test/`: contains Python tests, including tests that import the legacy Python implementation directly. Migrate needed coverage to Go tests or frontend tests, then remove the Python tests; keep only tests for supported code. ## Go-Specific Rules - Treat `internal/ingestion`, `internal/parser`, and `internal/deepdoc` as actively refactored code. Prefer collapsing duplicate paths over preserving transitional wrappers. @@ -66,11 +77,11 @@ Both sides reconcile by **column set, not by name**: Go's `hasUniqueIndex` (`int - A Python model existing does not mean Python owns that table's constraints. `pipeline_operation_log` has no `run_count` column and no unique index in `db_models.py`; both are added only by `internal/dao/migration.go`. ## Go Test Tiers -Go tests are classified by build tag so the default `go test ./...` run stays self-contained. Tag a test file with `//go:build ` placed before the `package` clause. +Go tests are classified by build tag. Tag a test file with `//go:build ` placed before the `package` clause. Run them through `build.sh` so the required CGO configuration and native libraries are available. | Tier | Build tag | Runs by default? | Needs | |---|---|---|---| -| Unit | (none) | Yes (`go test ./...`) | Native CGO static libs (wired by `build.sh --test`); no external services — uses in-memory SQLite, miniredis, or `httptest` stubs. | +| Unit | (none) | Yes (`bash build.sh --test`) | Native CGO static libs; no external services — uses in-memory SQLite, miniredis, or `httptest` stubs. | | Integration | `integration` | No (`-tags integration`) | A real service: MySQL/MinIO/Elasticsearch/Infinity/LLM. Single component, reasonably fast. | | E2E | `e2e` | No (`-tags e2e`) | Full cross-component pipeline (ingest → index → retrieve) against real services; heavy/slow. | | Manual | `manual` | No (`-tags manual`) | Very slow/expensive (deepdoc render/parity/snapshot/bench). **Local opt-in ONLY — never run in CI.** | @@ -87,12 +98,13 @@ bash build.sh --test-all # integration + e2e (never includes ma Rules: - New tests that touch a real external service MUST carry `integration`/`e2e`/`manual` — do not rely on `t.Skip` + env vars to soft-isolate them in the default unit run. Keep an env guard as a harmless secondary safety net if desired. - `manual` is never wired into CI or any automated pipeline. -- `unit` (no tag) must stay free of external-service dependencies so `go test ./...` passes without MySQL/MinIO/ES/Infinity/LLM. The native CGO static libraries (`office_oxide`/`pdfium`/`pdf_oxide`) are still required at build time and are wired automatically by `build.sh --test`; that is expected, not an external service. +- `unit` (no tag) must stay free of external-service dependencies so `bash build.sh --test` runs without MySQL/MinIO/ES/Infinity/LLM. The native CGO static libraries (`office_oxide`/`pdfium`/`pdf_oxide`) are still required at build time and are wired by `build.sh --test`; that is expected, not an external service. ## Working Rules - When reviewing documentation or code, inspect the full affected path and report all verifiable findings in one review; do not return after only a few findings and expose further issues in later rounds. - When handling review comments, independently verify each substantive claim against the current code or tests before accepting, rejecting, or acting on it. - Before editing, inspect the nearest code path that actually owns the behavior. +- For server changes, work in the Go implementation. If a Python behavior is still needed, port it to Go and test the Go path before removing the Python code. - Keep changes small and local unless the task is explicitly a broader refactor. - Prefer one implementation path instead of preserving old and new versions side by side. - Preserve behavior with focused tests when the behavior is still valid; do not keep tests that protect obsolete behavior. @@ -101,19 +113,20 @@ Rules: - When a maintainer takes over a community PR, a new commit generated by rewriting history (e.g. `merge`, `rebase -i`) must preserve the original author and add the maintainer as co-author (via a `Co-authored-by:` trailer) instead of overwriting the author with the maintainer alone. ## Commands -### Backend +### Go backend ```bash -uv sync --python 3.13 --all-extras -uv run python3 ragflow_deps/download_deps.py -docker compose -f docker/docker-compose-base.yml up -d -source .venv/bin/activate -export PYTHONPATH=$(pwd) -bash docker/launch_backend_service.sh -uv run pytest -ruff check -ruff format +bash build.sh --all # build native code and Go server +bash build.sh --go # build Go server with native library already built +bash build.sh --test ./internal/handler/... # targeted unit tests +bash build.sh --test # all unit tests +bash build.sh --test-integration ./... # integration tests; requires real services +bash build.sh --test-e2e # full-pipeline tests; requires real services +bash build.sh --test-manual # local opt-in only +bash build.sh --test-all # integration + e2e; excludes manual ``` +Native libraries and Go DeepDoc models currently come from `ragflow_deps/download_go_deps.py`; see `README_zh.md` for its isolated setup. The Go tokenizer also needs `ragflow_deps/cl100k_base.tiktoken`, which the current Python dependency pipeline provides. These are build/runtime resource preparation steps, not a Python server requirement. + ### Frontend ```bash cd web @@ -125,22 +138,13 @@ npm run test npm run type-check ``` -### Go -```bash -uv run ragflow_deps/download_deps.py -bash build.sh --test ./path/to/package/... -bash build.sh --go -# or build specific binaries: -bash build.sh --all -``` - ## Validation Preference - Run the narrowest relevant test, lint, or build command after a change. -- For backend changes, prefer targeted pytest or ruff checks over full-suite runs. +- For backend changes, first run package-scoped `bash build.sh --test ./path/to/package/...`. Run the integration or e2e tier when the changed behavior needs real services or a full pipeline. - For frontend changes, prefer the touched-package lint, type-check, or test command. -- For Go changes, prefer package-scoped `bash build.sh --test ...` first. - Do not default to raw `go test`, `go build`, or IDE Run/Debug for Go in this repo. They often miss the required CGO flags and native static libraries (`office_oxide`, `pdfium-static`, `pdf_oxide`) that `build.sh` wires correctly. -- If Go native builds fail, inspect `build.sh` and `internal/development.md` before changing code. Common environment issues are missing downloaded native deps and missing `lld` on Linux. +- After a Go build, execute the resulting binary's help command for each changed server mode; a successful link alone does not prove the binary starts. On this host, the original `build.sh` selected default LLD 18 and produced binaries that crashed before Go `main`; linking with LLD 20 started successfully. Verify the linker actually selected on Linux before trusting a new binary. +- If Go native builds fail, inspect `build.sh` and `internal/development.md` before changing code. Common environment issues are missing downloaded native dependencies or an incompatible `ld.lld` on Linux. ## Default review checklist - Remove instead of retaining `deprecated`, `legacy`, or compatibility-only code. diff --git a/README.md b/README.md index 3418232ddb..65cc01cf7d 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Static Badge - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Latest Release @@ -34,9 +34,6 @@ license - - Ask DeepWiki -

@@ -62,10 +59,7 @@ - 🔥 [Latest Updates](#-latest-updates) - 🌟 [Key Features](#-key-features) - 🔎 [System Architecture](#-system-architecture) -- 🎬 [Self-Hosting](#-self-hosting) -- 🔧 [Configurations](#-configurations) -- 🔧 [Build a Docker Image](#-build-a-docker-image) -- 🔨 [Launch Service from Source for Development](#-launch-service-from-source-for-development) +- 🏠 [Local Deployment](#-local-deployment) - 📚 [Documentation](#-documentation) - 📜 [Roadmap](#-roadmap) - 🏄 [Community](#-community) @@ -81,6 +75,8 @@ Try our cloud service at [https://cloud.ragflow.io](https://cloud.ragflow.io). +For local deployment, see [Local Deployment](#-local-deployment). +
Chunking demonstration Agentic workflow demonstration @@ -88,18 +84,17 @@ Try our cloud service at [https://cloud.ragflow.io](https://cloud.ragflow.io). ## 🔥 Latest Updates -- 2026-06-15 Support multiple chat channels such as Feishu, Discord, Telegram, Line, etc. -- 2026-04-24 Supports DeepSeek v4. -- 2026-03-24 [RAGFlow Skill on OpenClaw](https://clawhub.ai/yingfeng/ragflow-skill) — Provides an official skill for accessing RAGFlow datasets via OpenClaw. -- 2025-12-26 Supports 'Memory' for AI agent. -- 2025-11-19 Supports Gemini 3 Pro. -- 2025-11-12 Supports data synchronization from Confluence, S3, Notion, Discord, Google Drive. -- 2025-10-23 Supports MinerU & Docling as document parsing methods. -- 2025-10-15 Supports orchestrable ingestion pipeline. -- 2025-08-08 Supports OpenAI's latest GPT-5 series models. -- 2025-08-01 Supports agentic workflow and MCP. -- 2025-05-23 Adds a Python/JavaScript code executor component to Agent. -- 2025-03-19 Supports using a multi-modal model to make sense of images within PDF or DOCX files. +- 2026-09-10 Added website content ingestion through sitemaps. +- 2026-08-19 Introduced Knowledge Compilation to generate Wikis, Graphs, Trees, PageIndex, Mind Maps, Timelines, and Skills at the document and dataset levels. +- 2026-08-19 Introduced Agentic RAG with Low, Medium, High, and Ultra thinking modes. +- 2026-07-02 Added Google BigQuery data source ingestion and incremental synchronization. +- 2026-06-29 Added chat channels for WhatsApp, DingTalk, and WeCom. +- 2026-05-26 Added the Browser component, enabling Agents to browse and interact with web pages. +- 2026-04-21 Added seven built-in data ingestion pipeline templates. +- 2026-04-21 Added Agent application publishing, sandbox code execution, and chart generation. +- 2026-04-21 Added user-level memory storage and retrieval. + +See the [full release notes](./docs/release_notes.md) for more updates. ## 🎉 Stay Tuned @@ -114,7 +109,7 @@ releases! 🌟 ### 🍭 **"Quality in, quality out"** -- [Deep document understanding](./deepdoc/README.md)-based knowledge extraction from unstructured data with complicated +- Deep document understanding-based knowledge extraction from unstructured data with complicated formats. - Finds "needle in a data haystack" of literally unlimited tokens. @@ -123,6 +118,25 @@ releases! 🌟 - Intelligent and explainable. - Plenty of template options to choose from. +### 🧩 **Knowledge Compilation** + +- Compile content at the document and dataset levels into structured knowledge artifacts. +- Use compilation templates to generate Wikis, Graphs, Trees, PageIndex, Mind Maps, Timelines, and Skills for different knowledge organization and reuse needs. +- Configure compilation models and processing rules, and view, update, and regenerate knowledge artifacts. + +### 🧠 **Agentic Retrieval** + +- Perform multi-step retrieval for complex questions: the model analyzes the question and, when needed, breaks it down, retrieves knowledge, and verifies evidence. +- Gather more complete context through multiple rounds of retrieval and reasoning to help generate well-grounded answers. +- Choose Low, Medium, High, or Ultra thinking modes to control retrieval and reasoning depth according to question complexity. + +### ⚙️ **Go-native service architecture** + +- API, Admin, Ingestor, and Syncer are provided by a unified Go service. +- DeepDoc runs within the Go process and handles layout analysis, OCR, and table recognition. +- Go services use CGO to call native document parsing libraries and ONNX Runtime. +- MCP and Sandbox Executor are optional capabilities that can be enabled as needed. + ### 🌱 **Grounded citations with reduced hallucinations** - Visualization of text chunking to allow human intervention. @@ -142,26 +156,27 @@ releases! 🌟 ## 🔎 System Architecture
-RAGFlow system architecture +RAGFlow system architecture
-## 🎬 Self-Hosting +## 🏠 Local Deployment -### 📝 Prerequisites +### 🐳 Docker Deployment -- CPU >= 4 cores -- RAM >= 16 GB -- Disk >= 50 GB +#### 📝 Docker Deployment Prerequisites + +- Recommended starting configuration: 4 CPU cores, 16 GB RAM, and 50 GB of available disk space. Actual requirements depend on the document engine, data volume, parsing tasks, and concurrency. Local models and other optional components may require additional resources. - Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- Python >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/): Required only if you intend to use the code executor (sandbox) feature of RAGFlow. +- [gVisor](https://gvisor.dev/docs/user_guide/install/): Required only when using the Self-Managed container Sandbox. + +Docker deployment does not require Go on the host. Self-Managed container Sandbox requires gVisor; other Sandbox providers do not require gVisor on the RAGFlow host. > [!TIP] > If you have not installed Docker on your local machine (Windows, Mac, or Linux), see [Install Docker Engine](https://docs.docker.com/engine/install/). -### 🚀 Start up the server +#### 🚀 Start up the server -1. Ensure `vm.max_map_count` >= 262144: +1. If using Elasticsearch, set `vm.max_map_count` on the Docker host to at least 262144. This step is usually unnecessary with Infinity: > To check the value of `vm.max_map_count`: > @@ -169,7 +184,7 @@ releases! 🌟 > sysctl vm.max_map_count > ``` > - > Reset `vm.max_map_count` to a value at least 262144 if it is not. + > If you use Elasticsearch and the value is below 262144, reset it: > > ```bash > # In this case, we set it to 262144: @@ -182,217 +197,156 @@ releases! 🌟 > ```bash > vm.max_map_count=262144 > ``` -2. Clone the repo: +2. Clone the repository: ```bash git clone https://github.com/infiniflow/ragflow.git ``` -3. Start up the server using the pre-built Docker images: +3. Build the Go image and start the server with the Go Compose configuration: -> [!CAUTION] -> All Docker images are built for x86 platforms. We don't currently offer Docker images for ARM64. -> If you are on an ARM64 platform, follow [this guide](https://ragflow.io/docs/dev/build_docker_image) to build a Docker image compatible with your system. +> [!NOTE] +> The official Go image build target is `linux/amd64`. See the [Go Docker image build and platform support guide](./docs/develop/build_docker_image.mdx) for platform, resource, and macOS requirements. -> The command below downloads the `v0.27.2` edition of the RAGFlow Docker image. See the following table for descriptions of different RAGFlow editions. To download a RAGFlow edition different from `v0.27.2`, update the `RAGFLOW_IMAGE` variable accordingly in **docker/.env** before using `docker compose` to start the server. +> Build the Go image before the first deployment. Build time depends on network and machine performance. -```bash - cd ragflow/docker +Set the locally built image in **docker/.env** before starting Compose: - git checkout v0.27.2 - # Optional: use a stable tag (see releases: https://github.com/infiniflow/ragflow/releases) - # This step ensures the **entrypoint.sh** file in the code matches the Docker image version. - - # Use CPU for DeepDoc tasks: - docker compose -f docker-compose.yml up -d - - # To use GPU to accelerate DeepDoc tasks: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d +```dotenv +RAGFLOW_IMAGE=ragflow:go-local ``` -> Note: Prior to `v0.22.0`, we provided both images with embedding models and slim images without embedding models. Details as follows: +```bash +cd ragflow +docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . +cd docker +docker compose --env-file .env -f docker-compose.yml up -d +``` -| RAGFlow image tag | Image size (GB) | Has embedding models? | Stable? | -|-------------------|-----------------|-----------------------|----------------| -| v0.21.1 | ≈9 | ✔️ | Stable release | -| v0.21.1-slim | ≈2 | ❌ | Stable release | +In the default MySQL configuration, the Go image entrypoint runs database migrations before starting Syncer, Admin, API, and Ingestor through `bin/ragflow_server`. -> Starting with `v0.22.0`, we ship only the slim edition and no longer append the **-slim** suffix to the image tag. +> In the RAGFlow open-source 1.0 release, DeepDoc uses CPU inference for layout analysis, OCR, and table recognition. -4. Check the server status after having the server up and running: +4. Check service status and API readiness after startup: ```bash - docker logs -f docker-ragflow-cpu-1 + docker compose --env-file .env -f docker-compose.yml ps ``` - _The following output confirms a successful launch of the system:_ + The command above displays dependency status. RAGFlow itself does not define a Compose healthcheck; confirm readiness through its API: ```bash - - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) + curl -f http://localhost/api/v1/system/healthz ``` - > If you skip this confirmation step and directly log in to RAGFlow, your browser may prompt a `network abnormal` - > error because, at that moment, your RAGFlow may not be fully initialized. - > + An HTTP 200 response indicates readiness. If you changed `SVR_WEB_HTTP_PORT`, use that port in the health-check URL. If startup fails, inspect the relevant service logs with `docker compose --env-file .env -f docker-compose.yml logs --tail 50 `. 5. In your web browser, enter the IP address of your server and log in to RAGFlow. > With the default settings, you only need to enter `http://IP_OF_YOUR_MACHINE` (**sans** port number) as the default > HTTP serving port `80` can be omitted when using the default configurations. > -6. In [service_conf.yaml.template](./docker/service_conf.yaml.template), select the desired LLM factory in `user_default_llm` and update - the `API_KEY` field with the corresponding API key. - - > See [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup) for more information. - > +6. After signing in, add an LLM, embedding, and reranker on the model provider page, including the model name, service address, and API key. _The show is on!_ -## 🔧 Configurations +#### ⚙️ Docker Configuration and Adjustment -When it comes to system configurations, you will need to manage the following files: +Go Docker deployment uses `docker/.env` and `docker/docker-compose.yml`, uses Kvrocks for cache and Checkpoint storage, and uses NATS JetStream as the message queue. Configure the image, ports, passwords, document engine, and model image source as described in the [Docker configuration guide](./docker/README.md). For platform limitations and macOS requirements, see the [Go Docker image build and platform support guide](./docs/develop/build_docker_image.mdx). -- [.env](./docker/.env): Keeps the fundamental setups for the system, such as `SVR_HTTP_PORT`, `MYSQL_PASSWORD`, and - `MINIO_PASSWORD`. -- [service_conf.yaml.template](./docker/service_conf.yaml.template): Configures the back-end services. The environment variables in this file will be automatically populated when the Docker container starts. Any environment variables set within the Docker container will be available for use, allowing you to customize service behavior based on the deployment environment. -- [docker-compose.yml](./docker/docker-compose.yml): The system relies on [docker-compose.yml](./docker/docker-compose.yml) to start up. +For document-engine changes, configuration updates, restarting services, and retaining or removing existing data, follow the Docker configuration guide. -> The [./docker/README](./docker/README.md) file provides a detailed description of the environment settings and service -> configurations which can be used as `${ENV_VARS}` in the [service_conf.yaml.template](./docker/service_conf.yaml.template) file. +### 🔨 Launch Go Services from Source -To update the default HTTP serving port (80), go to [docker-compose.yml](./docker/docker-compose.yml) and change `80:80` -to `:80`. +#### 📝 Source Build Prerequisites -Updates to the above configurations require a reboot of all containers to take effect: +Install the Go version specified in `go.mod` (currently Go 1.27), Clang 20, LLD 20, CMake ≥ 4.0, PCRE2 development files, and the native libraries required by CGO. Node.js and npm are required only when developing the React frontend. -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -### Switch doc engine from Elasticsearch to Infinity - -RAGFlow uses Elasticsearch by default for storing full text and vectors. To switch to [Infinity](https://github.com/infiniflow/infinity/), follow these steps: - -1. Stop all running containers: - - ```bash - docker compose -f docker/docker-compose.yml down -v - ``` - -> [!WARNING] -> `-v` will delete the docker container volumes, and the existing data will be cleared. - -2. Set `DOC_ENGINE` in **docker/.env** to `infinity`. -3. Start the containers: - - ```bash - docker compose -f docker/docker-compose.yml up -d - ``` - -> [!WARNING] -> Switching to Infinity on a Linux/arm64 machine is not yet officially supported. - -## 🔧 Build a Docker Image - -This image is approximately 2 GB in size and relies on external LLM and embedding services. - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -Or if you are behind a proxy, you can pass proxy arguments: - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 Launch Service from Source for Development - -> [!IMPORTANT] -> After cloning the repository for the first time, run `git config --local --unset core.hooksPath`, `uv tool install lefthook` and `lefthook install` once from the repo root to enable local Git hooks. - -1. Install `uv`, or skip this step if it is already installed: - - ```bash - pipx install uv - ``` -2. Clone the source code and install Python dependencies: +1. Clone the repository and install the Go version specified in `go.mod` (currently Go 1.27), Clang 20, LLD 20, CMake ≥ 4.0, and PCRE2 development files. Go services depend on CGO and native static libraries; [build.sh](./build.sh) sets the required build parameters. ```bash git clone https://github.com/infiniflow/ragflow.git - cd ragflow/ - uv sync --python 3.13 # install RAGFlow dependent python modules - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + cd ragflow ``` -3. Launch the dependent services (MinIO, Elasticsearch, Redis, and MySQL) using Docker Compose: + +2. Prepare native libraries and model files with the [Go dependency download script](./ragflow_deps/download_go_deps.py), then build the Go services: ```bash - docker compose -f docker/docker-compose-base.yml up -d + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` - Add the following line to `/etc/hosts` to resolve all hosts specified in **docker/.env** to `127.0.0.1`: + The script prepares native libraries and model resources required for the Go build and needs `requests` and `huggingface-hub`. Skip this step if you have prepared the same resources by other means. When started from the repository root, Go services automatically find `rag/res/deepdoc`; to start from another directory, set `DEEPDOC_MODEL_DIR` to its absolute path. - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. If you cannot access HuggingFace, set the `HF_ENDPOINT` environment variable to use a mirror site: +3. Start the local dependencies and make sure the hosts and ports in **conf/service_conf.yaml** point to addresses accessible from the host. Go source services connect to Compose-exposed Kvrocks at `localhost:6379`, while Go Docker services connect to Kvrocks on the container network. If using the default Elasticsearch engine, set `vm.max_map_count` on the Docker host to at least `262144` first. ```bash - export HF_ENDPOINT=https://hf-mirror.com + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` -5. If your operating system does not have jemalloc, please install it as follows: + +4. Migrate the database first, then start the Go services in order in five separate terminals. Run each command below from the repository root. Keep the four service terminals running. The migration command does not need `RAGFLOW_DEV_MODE`; set `RAGFLOW_DEV_MODE=true` for Admin, Ingestor, Syncer, and API in a development environment. Close the migration terminal after the migration completes. + + Terminal 1: migrate the database. ```bash - # Ubuntu - sudo apt-get install libjemalloc-dev - # CentOS - sudo yum install jemalloc - # OpenSUSE - sudo zypper install jemalloc - # macOS - brew install jemalloc + ./bin/ragflow_server --migrate ``` -6. Launch backend service: + + Terminal 2: start Admin (target port `9381`). ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin ``` -7. Install frontend dependencies: + + Terminal 3: start Ingestor. + + ```bash + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + ``` + + Terminal 4: start Syncer. + + ```bash + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + ``` + + Terminal 5: start API (target port `9380`). + + ```bash + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api + ``` + + The startup modes work as follows: + + - `--migrate`: Runs database migrations and exits when complete. + - `--admin`: Starts the Admin service for management and initialization operations. + - `--ingestor`: Starts the Ingestor service for data ingestion and parsing tasks. + - `--syncer`: Starts the Syncer service for data synchronization tasks. + - `--api`: Starts the API service for the Web UI, SDKs, and external clients. + + `RAGFLOW_DEV_MODE=true` is only for development; it disables the downgrade check between code and database migration versions, but does not run migrations or change the database schema. Do not set it in production. Start Admin before the other services. After database migration, `RAGFLOW_DEV_MODE=true bash build.sh --run` can conveniently start Admin, Ingestor, and API. It does not start Syncer; start it separately with `RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer` for the complete service chain. + +5. Only when developing the frontend, install Node.js and npm, then start the React frontend: ```bash cd web npm install + API_PROXY_SCHEME=go npm run dev ``` -8. Launch frontend service: + + In another terminal, confirm that the Go API is ready: ```bash - npm run dev + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` - _The following output confirms a successful launch of the system:_ + An HTTP 200 response indicates that the API is responding. See [Launch Service from Source](./docs/develop/launch_ragflow_from_source.md#5-verify-the-startup) for complete frontend, ClickHouse, and DeepDoc verification steps. - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) -9. Stop RAGFlow front-end and back-end service after development is complete: + When development is complete, press `Ctrl+C` in each service terminal to stop the processes. To stop dependencies but keep the containers for next time, run `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse`. To remove the dependency containers and Compose network while keeping named data volumes, run `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`. - ```bash - pkill -f "ragflow_server.py|task_executor.py" - ``` +See [Launch Service from Source](./docs/develop/launch_ragflow_from_source.md) for details. ## 📚 Documentation diff --git a/README_ar.md b/README_ar.md index 3ca48a90c0..a83d645e6e 100644 --- a/README_ar.md +++ b/README_ar.md @@ -26,7 +26,7 @@ Static Badge - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Latest Release @@ -34,9 +34,6 @@ license - - Ask DeepWiki -

@@ -81,6 +78,8 @@ جرّب النسخة التجريبية على [https://cloud.ragflow.io](https://cloud.ragflow.io). +للنشر محليًا، راجع قسم [النشر المحلي](#-الاستضافة-الذاتية). +
Chunking demonstration Agentic workflow demonstration @@ -88,18 +87,17 @@ ## 🔥 آخر التحديثات -- 15-06-2026 يدعم قنوات دردشة متعددة مثل Feishu و Discord و Telegram و Line وما إلى ذلك. -- 24-04-2026 يدعم DeepSeek v4. -- 24-03-2026 [RAGFlow Skill on OpenClaw](https://clawhub.ai/yingfeng/ragflow-skill) — توفر مهارة رسمية للوصول إلى مجموعات بيانات RAGFlow عبر OpenClaw. -- 26-12-2025 يدعم ميزة "Memory" لوكلاء الذكاء الاصطناعي. -- 11-11-2025 يدعم Gemini 3 Pro. -- 12-11-2025 يدعم مزامنة البيانات من Confluence، S3، Notion، Discord، Google Drive. -- 23-10-2025 يدعم MinerU وDocling كطرق لتحليل المستندات. -- 15-10-2025 يدعم العرض الأوركسترالي pipeline. -- 08-08-2025 يدعم أحدث موديلات سلسلة OpenAI. -- 01-08-2025 يدعم سير العمل الوكيل وMCP. -- 23-05-2025 تمت إضافة مكون منفذ كود Python/JavaScript إلى Agent. -- 19-03-2025 يدعم استخدام نموذج متعدد الوسائط لفهم الصور داخل ملفات PDF أو DOCX. +- 2026-09-10 إضافة استيعاب محتوى الويب عبر خرائط المواقع. +- 2026-08-19 إطلاق Knowledge Compilation لإنشاء Wiki وGraph وTree وPageIndex وMind Map وTimeline وSkills على مستوى المستند ومجموعة البيانات. +- 2026-08-19 إطلاق Agentic RAG مع أوضاع التفكير Low وMedium وHigh وUltra. +- 2026-07-02 إضافة استيعاب مصادر بيانات Google BigQuery والمزامنة التدريجية. +- 2026-06-29 إضافة قنوات دردشة WhatsApp وDingTalk وWeCom. +- 2026-05-26 إضافة مكوّن Browser لتمكين Agents من تصفح صفحات الويب والتفاعل معها. +- 2026-04-21 إضافة سبعة قوالب مضمّنة لخطوط استيعاب البيانات. +- 2026-04-21 إضافة نشر تطبيقات Agent وتنفيذ التعليمات البرمجية في Sandbox وإنشاء المخططات. +- 2026-04-21 إضافة تخزين الذاكرة واسترجاعها على مستوى المستخدم. + +راجع [ملاحظات الإصدار الكاملة](./docs/release_notes.md) لمزيد من التحديثات. ## 🎉 تابعونا @@ -114,7 +112,7 @@ ### 🍭 **"الجودة في الداخل، الجودة في الخارج"** -- [الفهم العميق للمستندات](./deepdoc/README.md) لاستخراج المعرفة من البيانات غير المنظمة +- الفهم العميق للمستندات لاستخراج المعرفة من البيانات غير المنظمة ذات التنسيقات المعقدة. - يجد "إبرة في كومة قش بيانات" من الرموز غير المحدودة حرفيًا. @@ -123,6 +121,21 @@ - ذكي وقابل للتفسير. - الكثير من خيارات القالب للاختيار من بينها. +### 🧩 **تجميع المعرفة (Knowledge Compilation)** + +- يحوّل المحتوى على مستوى المستند ومجموعة البيانات إلى مخرجات معرفية منظمة، مثل Wiki وGraph وTree وPageIndex وMind Map وTimeline وSkills. +- يتيح ضبط نماذج التجميع وقواعد المعالجة، ثم عرض المخرجات وتحديثها وإعادة إنشائها. + +### 🧠 **الاسترجاع الوكيلي (Agentic Retrieval)** + +- يحلل الأسئلة المعقدة، ويقسمها عند الحاجة، ويسترجع المعرفة ويتحقق من الأدلة عبر خطوات متعددة. +- تدعم أوضاع التفكير Low وMedium وHigh وUltra ضبط عمق الاسترجاع والاستدلال حسب تعقيد السؤال. + +### ⚙️ **بنية خدمات Go الأصلية** + +- توفر خدمة Go موحدة API وAdmin وIngestor وSyncer. يعمل DeepDoc داخل عملية Go لتحليل التخطيط وOCR والتعرف على الجداول. +- تستدعي خدمات Go مكتبات تحليل المستندات الأصلية وONNX Runtime عبر CGO. ويمكن تفعيل MCP وSandbox Executor عند الحاجة. + ### 🌱 **استشهادات مؤرضة لتقليل الهلوسة** - تصور تقطيع النص للسماح بالتدخل البشري. @@ -142,24 +155,25 @@ ## 🔎 هندسة النظام
-RAGFlow system architecture +بنية RAGFlow
## 🎬 الاستضافة الذاتية -### 📝 المتطلبات الأساسية +### 🐳 نشر Docker -- CPU >= 4 مراكز -- الرام >= 16 جيجا -- القرص >= 50 جيجا بايت +#### 📝 متطلبات نشر Docker + +- التكوين الابتدائي الموصى به: 4 أنوية CPU وذاكرة RAM بسعة 16 GB ومساحة قرص متاحة تبلغ 50 GB. تختلف المتطلبات الفعلية حسب محرك المستندات وحجم البيانات ومهام التحليل والتزامن؛ وقد تتطلب النماذج المحلية والمكونات الاختيارية الأخرى موارد إضافية. - Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- بايثون >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/): مطلوب فقط إذا كنت تنوي استخدام ميزة منفذ التعليمات البرمجية (وضع الحماية) لـ RAGFlow. +- [gVisor](https://gvisor.dev/docs/user_guide/install/): مطلوب فقط عند استخدام Sandbox للحاويات Self-Managed. + +لا يتطلب نشر Docker تثبيت Go على المضيف. يتطلب Self-Managed container Sandbox تثبيت gVisor وإعداده؛ أما موفرو Sandbox الآخرون فلا يتطلبون تثبيت gVisor على مضيف RAGFlow. > [!TIP] > إذا لم تقم بتثبيت Docker على جهازك المحلي (Windows أو Mac أو Linux)، راجع [تثبيت Docker Engine](https://docs.docker.com/engine/install/). -### 🚀 بدء تشغيل الخادم +#### 🚀 بدء تشغيل الخادم 1. تأكد من `vm.max_map_count` >= 262144: @@ -194,203 +208,109 @@ > جميع الصور Docker مصممة لمنصات x86. لا نعرض حاليًا صور Docker لـ ARM64. > إذا كنت تستخدم نظامًا أساسيًا ARM64، فاتبع [هذا الدليل](https://ragflow.io/docs/dev/build_docker_image) لإنشاء صورة Docker متوافقة مع نظامك. -> يقوم الأمر أدناه بتنزيل إصدار `v0.27.2` من الصورة RAGFlow Docker. راجع الجدول التالي للحصول على أوصاف لإصدارات RAGFlow المختلفة. لتنزيل إصدار RAGFlow مختلف عن `v0.27.2`، قم بتحديث المتغير `RAGFLOW_IMAGE` وفقًا لذلك في **docker/.env** قبل استخدام `docker compose` لبدء تشغيل الخادم. +> اكتب `RAGFLOW_IMAGE=ragflow:go-local` في **docker/.env** قبل التشغيل. هدف البناء الرسمي لصورة Go هو `linux/amd64`. -```bash - cd ragflow/docker - - git checkout v0.27.2 - # Optional: use a stable tag (see releases: https://github.com/infiniflow/ragflow/releases) - # This step ensures the **entrypoint.sh** file in the code matches the Docker image version. - - # Use CPU for DeepDoc tasks: - docker compose -f docker-compose.yml up -d - - # To use GPU to accelerate DeepDoc tasks: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d +```dotenv +RAGFLOW_IMAGE=ragflow:go-local ``` -> ملاحظة: قبل `v0.22.0`، قدمنا ​​كلتا الصورتين بنماذج embedding وصورًا رفيعة بدون نماذج embedding. التفاصيل على النحو التالي: +```bash +cd ragflow +docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . +cd docker +docker compose --env-file .env -f docker-compose.yml up -d +``` -| RAGFlow علامة الصورة | حجم الصورة (جيجابايت) | هل لديه نماذج embedding؟ | مستقر؟ | -|-------------------|-----------------|-----------------------|----------------| -| v0.21.1 | ≈9 | ✔️ | إصدار مستقر | -| v0.21.1-slim | ≈2 | ❌ | إصدار مستقر | - -> بدءًا من `v0.22.0`، نقوم بشحن الإصدار النحيف فقط ولم نعد نلحق اللاحقة **-slim** بعلامة الصورة. +> يستخدم DeepDoc في الإصدار مفتوح المصدر 1.0 استدلال CPU لتحليل التخطيط وOCR والتعرف على الجداول. 4. التحقق من حالة الخادم بعد تشغيل الخادم: ```bash - docker logs -f docker-ragflow-cpu-1 + docker compose --env-file .env -f docker-compose.yml ps + curl -f http://localhost/api/v1/system/healthz ``` - _النتيجة التالية تؤكد الإطلاق الناجح للنظام:_ - - ```bash - - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) - ``` - - > إذا تخطيت خطوة التأكيد هذه وقمت بتسجيل الدخول مباشرة إلى RAGFlow، فقد يعرض متصفحك تنبيه `network abnormal` - > خطأ لأنه في تلك اللحظة، قد لا تتم تهيئة RAGFlow بشكل كامل. - > 5. في متصفح الويب الخاص بك، أدخل عنوان IP الخاص بالخادم الخاص بك وقم بتسجيل الدخول إلى RAGFlow. > باستخدام الإعدادات الافتراضية، ما عليك سوى إدخال `http://IP_OF_YOUR_MACHINE` (**من دون** رقم المنفذ) كإعداد افتراضي > HTTP يمكن حذف منفذ العرض `80` عند استخدام التكوينات الافتراضية. > -6. في [service_conf.yaml.template](./docker/service_conf.yaml.template)، حدد المصنع LLM المطلوب في `user_default_llm` وقم بالتحديث - الحقل `API_KEY` مع مفتاح API المقابل. +6. بعد تسجيل الدخول، أضف LLM ونموذج embedding ونموذج reranker من صفحة موفري النماذج، ثم أدخل اسم النموذج وعنوان الخدمة ومفتاح API. > راجع [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup) لمزيد من المعلومات. > _العرض بدأ!_ -## 🔧 التكوينات +#### ⚙️ إعداد Docker وتعديله -عندما يتعلق الأمر بتكوينات النظام، ستحتاج إلى إدارة الملفات التالية: +يستخدم نشر Go عبر Docker الملفين `docker/.env` و`docker/docker-compose.yml`، ويستخدم Kvrocks لتخزين ذاكرة التخزين المؤقت ونقاط التحقق، كما يستخدم NATS JetStream كقائمة انتظار للرسائل. لتعديل الصورة والمنافذ وكلمات المرور ومحرك المستندات ومصدر صور النماذج، اتبع [دليل إعداد Docker](./docker/README.md). ولقيود المنصات ومتطلبات macOS، راجع [دليل بناء صورة Go ودعم المنصات](./docs/develop/build_docker_image.mdx). -- [.env](./docker/.env): يحتفظ بالإعدادات الأساسية للنظام، مثل `SVR_HTTP_PORT`، `MYSQL_PASSWORD`، و - `MINIO_PASSWORD`. -- [service_conf.yaml.template](./docker/service_conf.yaml.template): تكوين الخدمات الخلفية. سيتم ملء متغيرات البيئة في هذا الملف تلقائيًا عند بدء تشغيل الحاوية Docker. ستكون أي متغيرات بيئة تم تعيينها داخل حاوية Docker متاحة للاستخدام، مما يسمح لك بتخصيص سلوك الخدمة استنادًا إلى بيئة النشر. -- [docker-compose.yml](./docker/docker-compose.yml): يعتمد النظام على [docker-compose.yml](./docker/docker-compose.yml) لبدء التشغيل. +عند تبديل محرك المستندات أو تعديل الإعدادات وإعادة تشغيل الخدمات أو الاحتفاظ بالبيانات الحالية أو حذفها، اتبع أيضًا دليل إعداد Docker أعلاه. -> يوفر الملف [./docker/README](./docker/README.md) وصفًا تفصيليًا لإعدادات البيئة والخدمة -> التكوينات التي يمكن استخدامها كـ `${ENV_VARS}` في ملف [service_conf.yaml.template](./docker/service_conf.yaml.template). +### 🔨 إطلاق الخدمة من المصدر للتطوير -لتحديث منفذ العرض الافتراضي HTTP (80)، انتقل إلى [docker-compose.yml](./docker/docker-compose.yml) وقم بتغيير `80:80` -إلى `:80`. +#### 📝 متطلبات البناء من المصدر -تتطلب تحديثات التكوينات المذكورة أعلاه إعادة تشغيل جميع الحاويات لتصبح سارية المفعول: - -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -### تبديل محرك المستندات من Elasticsearch إلى Infinity - -RAGFlow يستخدم Elasticsearch بشكل افتراضي لتخزين النص الكامل والمتجهات. للتبديل إلى [Infinity](https://github.com/infiniflow/infinity/)، اتبع الخطوات التالية: - -1. إيقاف كافة الحاويات قيد التشغيل: - - ```bash - docker compose -f docker/docker-compose.yml down -v - ``` - -> [!WARNING] -> `-v` سوف يحذف docker وحدات تخزين الحاوية، وسيتم مسح البيانات الموجودة. - -2. اضبط `DOC_ENGINE` في **docker/.env** على `infinity`. -3. ابدأ الحاويات: - - ```bash - docker compose -f docker/docker-compose.yml up -d - ``` - -> [!WARNING] -> التبديل إلى Infinity على جهاز Linux/arm64 غير مدعوم رسميًا بعد. - -## 🔧 أنشئ صورة Docker - -يبلغ حجم هذه الصورة حوالي 2 غيغابايت وتعتمد على خدمات LLM وembedding الخارجية. - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -أو إذا كنت خلف وكيل، فيمكنك تمرير وسيطات الوكيل: - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 إطلاق الخدمة من المصدر للتطوير - -1. قم بتثبيت `uv`، أو قم بتخطي هذه الخطوة إذا كان مثبتًا بالفعل: - - ```bash - pipx install uv - ``` -2. استنساخ الكود المصدري وتثبيت تبعيات بايثون: +1. ثبّت إصدار Go المحدد في `go.mod` (حاليًا Go 1.27)، وClang 20 وLLD 20 وCMake 4.0 أو أحدث وملفات تطوير PCRE2. تعتمد خدمات Go على CGO والمكتبات الأصلية؛ ويضبط [build.sh](./build.sh) خيارات البناء اللازمة. +2. استنسخ المستودع وجهّز المكتبات الأصلية وملفات النماذج المطلوبة للبناء، ثم ابنِ خدمات Go: ```bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/ - uv sync --python 3.13 # install RAGFlow dependent python modules - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` -3. قم بتشغيل الخدمات التابعة (MinIO وElasticsearch وRedis وMySQL) باستخدام Docker Compose: + + يجهّز البرنامج النصي المكتبات الأصلية وموارد النماذج اللازمة لبناء Go، ويحتاج إلى `requests` و`huggingface-hub`. يمكن تخطي هذه الخطوة إذا جُهزت الموارد نفسها بطريقة أخرى. عند التشغيل من جذر المستودع، تعثر خدمات Go تلقائيًا على `rag/res/deepdoc`؛ وللتشغيل من دليل آخر، اضبط `DEEPDOC_MODEL_DIR` على المسار المطلق لذلك الدليل. +3. ابدأ الخدمات التابعة المطلوبة (Elasticsearch وMySQL وMinIO وNATS وKvrocks وClickHouse) باستخدام Docker Compose: ```bash - docker compose -f docker/docker-compose-base.yml up -d + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` - أضف السطر التالي إلى `/etc/hosts` لحل كافة المضيفين المحددين في **docker/.env** إلى `127.0.0.1`: + تتصل خدمات Go التي تعمل من المصدر بـ Kvrocks عبر `localhost:6379`، ولا يتطلب التكوين المرفق تعديل `/etc/hosts`. - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. إذا لم تتمكن من الوصول إلى HuggingFace، فقم بتعيين متغير البيئة `HF_ENDPOINT` لاستخدام موقع مرآة: +4. بعد اكتمال ترحيل قاعدة البيانات، شغّل الخدمات بالترتيب. نفّذ كل أمر في نافذة طرفية مستقلة ومن جذر المستودع، واترك نوافذ الخدمات الأربع مفتوحة: ```bash - export HF_ENDPOINT=https://hf-mirror.com + ./bin/ragflow_server --migrate + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api ``` -5. إذا كان نظام التشغيل لديك لا يحتوي على jemalloc، فيرجى تثبيته على النحو التالي: - ```bash - # Ubuntu - sudo apt-get install libjemalloc-dev - # CentOS - sudo yum install jemalloc - # OpenSUSE - sudo zypper install jemalloc - # macOS - brew install jemalloc - ``` -6. إطلاق الخدمة الخلفية: + تعمل أوضاع التشغيل كما يلي: - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh - ``` -7. تثبيت تبعيات الواجهة الأمامية: + - `--migrate`: ينفذ ترحيلات قاعدة البيانات ثم يخرج. + - `--admin`: يشغّل خدمة Admin للإدارة والتهيئة. + - `--ingestor`: يشغّل خدمة Ingestor لمهام استيعاب البيانات وتحليلها. + - `--syncer`: يشغّل خدمة Syncer لمهام مزامنة البيانات. + - `--api`: يشغّل خدمة API لواجهة الويب وSDK والعملاء الخارجيين. + + يُستخدم `RAGFLOW_DEV_MODE=true` للتطوير فقط؛ فهو يعطّل فحص الرجوع بين إصدار الكود وإصدار ترحيل قاعدة البيانات، ولا ينفذ الترحيلات أو يغير المخطط. لا تستخدمه في الإنتاج. شغّل Admin قبل الخدمات الأخرى. بعد الترحيل، يشغّل `RAGFLOW_DEV_MODE=true bash build.sh --run` خدمات Admin وIngestor وAPI، لكنه لا يشغّل Syncer؛ شغّل Syncer منفصلًا باستخدام `RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer` عند الحاجة إلى السلسلة الكاملة. +5. ثبّت Node.js وnpm وشغّل واجهة React فقط عند تطوير الواجهة الأمامية: ```bash cd web npm install + API_PROXY_SCHEME=go npm run dev ``` -8. إطلاق خدمة الواجهة الأمامية: + + تحقق من جاهزية Go API من نافذة طرفية أخرى: ```bash - npm run dev + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` - _النتيجة التالية تؤكد الإطلاق الناجح للنظام:_ + تعني استجابة HTTP 200 أن API يستجيب. عند انتهاء التطوير، اضغط `Ctrl+C` في كل نافذة خدمة. لإيقاف الخدمات التابعة مع الاحتفاظ بالحاويات، شغّل `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse`. ولإزالة حاويات الخدمات التابعة وشبكة Compose مع الاحتفاظ بوحدات التخزين المسماة، شغّل `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`. - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) -9. أوقف خدمة الواجهة الأمامية والخلفية RAGFlow بعد اكتمال التطوير: - - ```bash - pkill -f "ragflow_server.py|task_executor.py" - ``` +راجع [تشغيل الخدمة من المصدر](./docs/develop/launch_ragflow_from_source.md) لمزيد من التفاصيل. ## 📚 التوثيق diff --git a/README_fr.md b/README_fr.md index 4cd20b76a9..ec3f21c39e 100644 --- a/README_fr.md +++ b/README_fr.md @@ -26,7 +26,7 @@ Badge statique - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Dernière version @@ -34,9 +34,6 @@ licence - - Ask DeepWiki -

@@ -88,18 +85,17 @@ Essayez notre service cloud sur [https://cloud.ragflow.io](https://cloud.ragflow ## 🔥 Dernières mises à jour -- 15-06-2026 Prise en charge de plusieurs canaux de discussion tels que Feishu, Discord, Telegram, Line, etc. -- 24-04-2026 Prise en charge de DeepSeek v4. -- 24-03-2026 [RAGFlow Skill on OpenClaw](https://clawhub.ai/yingfeng/ragflow-skill) — Fournit un skill officiel pour accéder aux datasets RAGFlow via OpenClaw. -- 26-12-2025 Prise en charge de la « Mémoire » pour l'agent IA. -- 19-11-2025 Prise en charge de Gemini 3 Pro. -- 12-11-2025 Prise en charge de la synchronisation de données depuis Confluence, S3, Notion, Discord et Google Drive. -- 23-10-2025 Prise en charge de MinerU & Docling comme méthodes d'analyse de documents. -- 15-10-2025 Prise en charge du pipeline d'ingestion orchestrable. -- 08-08-2025 Prise en charge des derniers modèles de la série GPT-5 d'OpenAI. -- 01-08-2025 Prise en charge du flux de travail agentique et de MCP. -- 23-05-2025 Ajout d'un composant exécuteur de code Python/JavaScript à l'Agent. -- 19-03-2025 Prise en charge de l'utilisation d'un modèle multi-modal pour analyser les images dans les fichiers PDF ou DOCX. +- 2026-09-10 Ajout de l’ingestion de contenus Web à partir de sitemaps. +- 2026-08-19 Lancement de Knowledge Compilation pour générer des wikis, graphes, arbres, PageIndex, cartes mentales, chronologies et compétences au niveau des documents et des bases de connaissances. +- 2026-08-19 Lancement d’Agentic RAG avec quatre modes de réflexion : Low, Medium, High et Ultra. +- 2026-07-02 Ajout de l’ingestion de données depuis Google BigQuery et de la synchronisation incrémentielle. +- 2026-06-29 Ajout de canaux de conversation WhatsApp, DingTalk et WeCom. +- 2026-05-26 Ajout du composant Browser, qui permet aux Agents de parcourir et d’utiliser des pages Web. +- 2026-04-21 Ajout de sept modèles prédéfinis de pipelines d’ingestion de données. +- 2026-04-21 Ajout de la publication d’applications Agent, de l’exécution de code en sandbox et de la génération de graphiques. +- 2026-04-21 Ajout du stockage et de la récupération de mémoire au niveau utilisateur. + +Consultez les [notes de version complètes](./docs/release_notes.md) pour découvrir les autres nouveautés. ## 🎉 Restez informé @@ -113,7 +109,7 @@ Essayez notre service cloud sur [https://cloud.ragflow.io](https://cloud.ragflow ### 🍭 **"Quality in, quality out"** -- Extraction de connaissances basée sur la [compréhension approfondie des documents](./deepdoc/README.md) à partir de données non structurées aux formats complexes. +- Extraction de connaissances basée sur la compréhension approfondie des documents à partir de données non structurées aux formats complexes. - Trouve "l'aiguille dans la meule de données" de tokens littéralement illimités. ### 🍱 **Découpage(Chunking) basé sur des templates** @@ -121,6 +117,21 @@ Essayez notre service cloud sur [https://cloud.ragflow.io](https://cloud.ragflow - Intelligent et explicable. - De nombreuses options de templates disponibles. +### 🧩 **Compilation des connaissances (Knowledge Compilation)** + +- Transformez le contenu des documents et des jeux de données en connaissances structurées, notamment Wiki, Graph, Tree, PageIndex, Mind Map, Timeline et Skills. +- Configurez les modèles et règles de traitement, puis consultez, mettez à jour ou régénérez les résultats. + +### 🧠 **Recherche agentique (Agentic Retrieval)** + +- Le modèle analyse les questions complexes et peut les décomposer, rechercher des connaissances et vérifier les preuves en plusieurs étapes. +- Les modes Low, Medium, High et Ultra permettent de régler la profondeur de recherche et de raisonnement selon la complexité de la question. + +### ⚙️ **Architecture de services native Go** + +- Une implémentation Go unifiée fournit API, Admin, Ingestor et Syncer. DeepDoc s’exécute dans le processus Go pour l’analyse de mise en page, l’OCR et la reconnaissance des tableaux. +- Les services Go appellent les bibliothèques natives d’analyse de documents et ONNX Runtime via CGO. MCP et Sandbox Executor sont activables à la demande. + ### 🌱 **Citations fondées avec réduction des hallucinations** - Visualisation du découpage de texte pour permettre une intervention humaine. @@ -140,24 +151,25 @@ Essayez notre service cloud sur [https://cloud.ragflow.io](https://cloud.ragflow ## 🔎 Architecture du système
-RAGFlow system architecture +Architecture du système RAGFlow
## 🎬 Auto-hébergement -### 📝 Prérequis +### 🐳 Déploiement Docker -- CPU >= 4 cœurs -- RAM >= 16 Go -- Disque >= 50 Go +#### 📝 Prérequis du déploiement Docker + +- Configuration de départ recommandée : 4 cœurs CPU, 16 Go de RAM et 50 Go d’espace disque disponible. Les besoins réels dépendent du moteur de documents, du volume de données, des tâches d’analyse et de la concurrence. Les modèles locaux et les autres composants facultatifs peuvent nécessiter des ressources supplémentaires. - Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- Python >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/) : Requis uniquement si vous souhaitez utiliser la fonctionnalité d'exécuteur de code (sandbox) de RAGFlow. +- [gVisor](https://gvisor.dev/docs/user_guide/install/) : requis uniquement avec le Sandbox de conteneurs Self-Managed. + +Le déploiement Docker ne nécessite pas l’installation de Go sur l’hôte. Le Sandbox de conteneurs Self-Managed nécessite l’installation et la configuration de gVisor ; les autres fournisseurs de Sandbox n’en ont pas besoin sur l’hôte RAGFlow. > [!TIP] > Si vous n'avez pas installé Docker sur votre machine locale (Windows, Mac ou Linux), consultez [Installer Docker Engine](https://docs.docker.com/engine/install/). -### 🚀 Démarrer le serveur +#### 🚀 Démarrer le serveur 1. Assurez-vous que `vm.max_map_count` >= 262144 : @@ -185,204 +197,124 @@ Essayez notre service cloud sur [https://cloud.ragflow.io](https://cloud.ragflow ```bash git clone https://github.com/infiniflow/ragflow.git ``` -3. Démarrez le serveur en utilisant les images Docker préconstruites : +3. Construisez l’image Go et démarrez le serveur avec la configuration Compose Go. La cible de construction officielle est `linux/amd64`. Consultez le [guide de construction de l’image Go et de prise en charge des plateformes](./docs/develop/build_docker_image.mdx) pour connaître les exigences détaillées. -> [!CAUTION] -> Toutes les images Docker sont construites pour les plateformes x86. Nous ne proposons pas actuellement d'images Docker pour ARM64. -> Si vous êtes sur une plateforme ARM64, suivez [ce guide](https://ragflow.io/docs/dev/build_docker_image) pour construire une image Docker compatible avec votre système. + Avant le premier déploiement, définissez `RAGFLOW_IMAGE=ragflow:go-local` dans **docker/.env**, puis exécutez depuis la racine du dépôt : -> La commande ci-dessous télécharge l'édition `v0.27.2` de l'image Docker RAGFlow. Consultez le tableau suivant pour les descriptions des différentes éditions de RAGFlow. Pour télécharger une édition de RAGFlow différente de `v0.27.2`, mettez à jour la variable `RAGFLOW_IMAGE` dans **docker/.env** avant d'utiliser `docker compose` pour démarrer le serveur. - -```bash - cd ragflow/docker - - git checkout v0.27.2 - # Optionnel : utiliser un tag stable (voir les versions : https://github.com/infiniflow/ragflow/releases) - # Cette étape garantit que le fichier **entrypoint.sh** dans le code correspond à la version de l'image Docker. - - # Use CPU for DeepDoc tasks: - docker compose -f docker-compose.yml up -d - - # To use GPU to accelerate DeepDoc tasks: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d -``` - -> Remarque : Avant `v0.22.0`, nous fournissions à la fois des images avec des modèles d'embedding et des images slim sans modèles d'embedding. Détails ci-dessous : - -| RAGFlow image tag | Image size (GB) | Has embedding models? | Stable? | -|-------------------|-----------------|-----------------------|----------------| -| v0.21.1 | ≈9 | ✔️ | Stable release | -| v0.21.1-slim | ≈2 | ❌ | Stable release | - -> À partir de `v0.22.0`, nous ne distribuons que l'édition slim et ne rajoutons plus le suffixe **-slim** au tag d'image. - -4. Vérifiez l'état du serveur après son démarrage : - - ```bash - docker logs -f docker-ragflow-cpu-1 + ```dotenv + RAGFLOW_IMAGE=ragflow:go-local ``` - _La sortie suivante confirme un lancement réussi du système :_ - ```bash - - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) + cd ragflow + docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . + cd docker + docker compose --env-file .env -f docker-compose.yml up -d ``` - > Si vous sautez cette étape de confirmation et vous connectez directement à RAGFlow, votre navigateur peut afficher une erreur `network abnormal`, car à ce moment-là, votre RAGFlow peut ne pas être entièrement initialisé. + Avec la configuration MySQL par défaut, le point d’entrée de l’image exécute d’abord les migrations, puis démarre Syncer, Admin, API et Ingestor via `bin/ragflow_server`. Dans RAGFlow open-source 1.0, DeepDoc utilise l’inférence CPU pour l’analyse de mise en page, l’OCR et la reconnaissance des tableaux. + +4. Vérifiez l’état des dépendances avec `docker compose --env-file .env -f docker-compose.yml ps`, puis confirmez que RAGFlow est prêt avec l’interface HTTP (le conteneur RAGFlow ne définit pas de healthcheck Compose) : + + ```bash + curl -f http://localhost/api/v1/system/healthz + ``` + + Une réponse HTTP 200 indique que le service est prêt. Si `SVR_WEB_HTTP_PORT` a été modifié, utilisez ce port dans l’URL. En cas d’échec du démarrage, consultez les journaux du service concerné avec Compose. > 5. Dans votre navigateur web, entrez l'adresse IP de votre serveur et connectez-vous à RAGFlow. > Avec les paramètres par défaut, il vous suffit d'entrer `http://IP_OF_YOUR_MACHINE` (**sans** numéro de port), car le port HTTP par défaut `80` peut être omis lors de l'utilisation des configurations par défaut. > -6. Dans [service_conf.yaml.template](./docker/service_conf.yaml.template), sélectionnez la fabrique LLM souhaitée dans `user_default_llm` et mettez à jour le champ `API_KEY` avec la clé API correspondante. +6. Après vous être connecté à RAGFlow, ajoutez le LLM, le modèle d'embedding et le reranker sur la page des fournisseurs de modèles, puis renseignez le nom du modèle, l'adresse du service et la clé API correspondants. > Voir [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup) pour plus d'informations. > _Le spectacle commence !_ -## 🔧 Configurations +#### ⚙️ Configuration et ajustement de Docker -En ce qui concerne les configurations système, vous devrez gérer les fichiers suivants : +Le déploiement Docker Go utilise `docker/.env` et `docker/docker-compose.yml`, Kvrocks pour le cache et le stockage des Checkpoints, et NATS JetStream comme file de messages. Pour configurer l’image, les ports, les mots de passe, le moteur de documents et la source des images de modèles, consultez le [guide de configuration Docker](./docker/README.md). Pour les limites de plateforme et les exigences macOS, consultez le [guide de construction de l’image Go et de prise en charge des plateformes](./docs/develop/build_docker_image.mdx). -- [.env](./docker/.env) : Conserve les paramètres de base du système, tels que `SVR_HTTP_PORT`, `MYSQL_PASSWORD` et `MINIO_PASSWORD`. -- [service_conf.yaml.template](./docker/service_conf.yaml.template) : Configure les services back-end. Les variables d'environnement dans ce fichier seront automatiquement renseignées au démarrage du conteneur Docker. Toutes les variables d'environnement définies dans le conteneur Docker seront disponibles, vous permettant de personnaliser le comportement du service en fonction de l'environnement de déploiement. -- [docker-compose.yml](./docker/docker-compose.yml) : Le système s'appuie sur [docker-compose.yml](./docker/docker-compose.yml) pour démarrer. +Pour changer de moteur de documents, modifier la configuration, redémarrer les services ou conserver/supprimer les données existantes, suivez également le guide de configuration Docker ci-dessus. -> Le fichier [./docker/README](./docker/README.md) fournit une description détaillée des paramètres d'environnement et des configurations de services qui peuvent être utilisés comme `${ENV_VARS}` dans le fichier [service_conf.yaml.template](./docker/service_conf.yaml.template). +### 🔨 Lancer le service depuis les sources pour le développement -Pour mettre à jour le port HTTP de service par défaut (80), accédez à [docker-compose.yml](./docker/docker-compose.yml) et changez `80:80` en `:80`. +#### 📝 Prérequis de la compilation depuis les sources -Les mises à jour des configurations ci-dessus nécessitent un redémarrage de tous les conteneurs pour prendre effet : - -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -### Passer du moteur de documents Elasticsearch à Infinity - -RAGFlow utilise Elasticsearch par défaut pour stocker le texte intégral et les vecteurs. Pour passer à [Infinity](https://github.com/infiniflow/infinity/), suivez ces étapes : - -1. Arrêtez tous les conteneurs en cours d'exécution : - - ```bash - docker compose -f docker/docker-compose.yml down -v - ``` - -> [!WARNING] -> `-v` supprimera les volumes des conteneurs Docker, et les données existantes seront effacées. - -2. Définissez `DOC_ENGINE` dans **docker/.env** sur `infinity`. -3. Démarrez les conteneurs : - - ```bash - docker compose -f docker/docker-compose.yml up -d - ``` - -> [!WARNING] -> Le passage à Infinity sur une machine Linux/arm64 n'est pas encore officiellement pris en charge. - -## 🔧 Construire une image Docker - -Cette image fait environ 2 Go et dépend de services LLM et d'embedding externes. - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -Ou si vous êtes derrière un proxy, vous pouvez passer des arguments de proxy : - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 Lancer le service depuis les sources pour le développement - -1. Installez `uv`, ou ignorez cette étape s'il est déjà installé : - - ```bash - pipx install uv - ``` -2. Clonez le code source et installez les dépendances Python : +1. Installez la version de Go indiquée dans `go.mod` (Go 1.27 actuellement), Clang 20, LLD 20, CMake 4.0 ou version ultérieure, ainsi que les fichiers de développement PCRE2. Les services Go dépendent de CGO et de bibliothèques natives ; [build.sh](./build.sh) configure les paramètres nécessaires. +2. Clonez le dépôt, préparez les bibliothèques natives et les fichiers de modèles requis, puis compilez les services Go : ```bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/ - uv sync --python 3.13 # install RAGFlow dependent python modules - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` -3. Lancez les services dépendants (MinIO, Elasticsearch, Redis et MySQL) avec Docker Compose : + + Le script prépare les bibliothèques natives et les ressources de modèles nécessaires à la compilation Go et requiert `requests` et `huggingface-hub`. Ignorez cette étape si vous avez préparé les mêmes ressources autrement. Depuis la racine du dépôt, les services Go trouvent automatiquement `rag/res/deepdoc` ; depuis un autre répertoire, définissez `DEEPDOC_MODEL_DIR` sur son chemin absolu. +3. Lancez les dépendances requises (Elasticsearch, MySQL, MinIO, NATS, Kvrocks et ClickHouse) avec Docker Compose : ```bash - docker compose -f docker/docker-compose-base.yml up -d + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` - Ajoutez la ligne suivante à `/etc/hosts` pour résoudre tous les hôtes spécifiés dans **docker/.env** vers `127.0.0.1` : - - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. Si vous ne pouvez pas accéder à HuggingFace, définissez la variable d'environnement `HF_ENDPOINT` pour utiliser un site miroir : + Les services Go lancés depuis les sources se connectent à Kvrocks via `localhost:6379`, tandis que les services Docker utilisent le nom d'hôte du réseau de conteneurs. Aucune modification de `/etc/hosts` n'est nécessaire avec la configuration fournie. +4. Exécutez d'abord la migration, puis démarrez Admin, Ingestor, Syncer et API dans quatre terminaux distincts depuis la racine du dépôt. Le terminal de migration peut être fermé une fois la commande terminée ; les quatre autres doivent rester ouverts : ```bash - export HF_ENDPOINT=https://hf-mirror.com - ``` -5. Si votre système d'exploitation n'a pas jemalloc, installez-le comme suit : + # Terminal 1 : migration + ./bin/ragflow_server --migrate - ```bash - # Ubuntu - sudo apt-get install libjemalloc-dev - # CentOS - sudo yum install jemalloc - # OpenSUSE - sudo zypper install jemalloc - # macOS - brew install jemalloc - ``` -6. Lancez le service back-end : + # Terminal 2 : Admin, port cible 9381 + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh + # Terminal 3 : Ingestor + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + + # Terminal 4 : Syncer + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + + # Terminal 5 : API, port cible 9380 + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api ``` -7. Installez les dépendances front-end : + + Les modes de démarrage fonctionnent comme suit : + + - `--migrate` : exécute les migrations de base de données puis quitte. + - `--admin` : démarre le service Admin pour les opérations de gestion et d'initialisation. + - `--ingestor` : démarre le service Ingestor pour l'ingestion et l'analyse des données. + - `--syncer` : démarre le service Syncer pour la synchronisation des données. + - `--api` : démarre le service API pour l'interface Web, les SDK et les clients externes. + + `RAGFLOW_DEV_MODE=true` est réservé au développement. Il désactive le contrôle de rétrogradation entre la version du code et celle des migrations, mais n'exécute aucune migration et ne modifie pas le schéma. Ne l'utilisez pas en production. Après la migration, `RAGFLOW_DEV_MODE=true bash build.sh --run` peut démarrer Admin, Ingestor et API, mais pas Syncer. +5. Installez Node.js et npm uniquement pour développer le front-end : ```bash cd web npm install ``` -8. Lancez le service front-end : + Lancez ensuite le service front-end : ```bash - npm run dev + API_PROXY_SCHEME=go npm run dev ``` - _La sortie suivante confirme un lancement réussi du système :_ - - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) -9. Arrêtez les services front-end et back-end de RAGFlow une fois le développement terminé : + Dans un autre terminal, vérifiez ensuite que l'API Go est prête : ```bash - pkill -f "ragflow_server.py|task_executor.py" + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` + Une réponse HTTP 200 indique que l'API répond. À la fin du développement, appuyez sur `Ctrl+C` dans chaque terminal de service. Pour arrêter les dépendances sans supprimer les conteneurs, exécutez `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse`. Pour supprimer les conteneurs de dépendances et le réseau Compose tout en conservant les volumes nommés, exécutez `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`. + +Consultez [Lancer le service depuis les sources](./docs/develop/launch_ragflow_from_source.md) pour plus de détails. + ## 📚 Documentation - [Quickstart](https://ragflow.io/docs/dev/) diff --git a/README_id.md b/README_id.md index 6a6f2c4509..a8ccdd55a5 100644 --- a/README_id.md +++ b/README_id.md @@ -26,7 +26,7 @@ Lencana Daring - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Rilis Terbaru @@ -34,9 +34,6 @@ Lisensi - - Ask DeepWiki -

@@ -88,18 +85,17 @@ Coba layanan cloud kami di [https://cloud.ragflow.io](https://cloud.ragflow.io). ## 🔥 Pembaruan Terbaru -- 2026-06-15 Mendukung berbagai saluran obrolan seperti Feishu, Discord, Telegram, Line, dll. -- 2026-04-24 Mendukung DeepSeek v4. -- 2026-03-24 [RAGFlow Skill on OpenClaw](https://clawhub.ai/yingfeng/ragflow-skill) — Menyediakan skill resmi untuk mengakses dataset RAGFlow melalui OpenClaw. -- 2025-12-26 Mendukung 'Memori' untuk agen AI. -- 2025-11-19 Mendukung Gemini 3 Pro. -- 2025-11-12 Mendukung sinkronisasi data dari Confluence, S3, Notion, Discord, Google Drive. -- 2025-10-23 Mendukung MinerU & Docling sebagai metode penguraian dokumen. -- 2025-10-15 Dukungan untuk jalur data yang terorkestrasi. -- 2025-08-08 Mendukung model seri GPT-5 terbaru dari OpenAI. -- 2025-08-01 Mendukung alur kerja agen dan MCP. -- 2025-05-23 Menambahkan komponen pelaksana kode Python/JS ke Agen. -- 2025-03-19 Mendukung penggunaan model multi-modal untuk memahami gambar di dalam file PDF atau DOCX. +- 2026-09-10 Menambahkan ingest konten situs web melalui sitemap. +- 2026-08-19 Memperkenalkan Knowledge Compilation untuk menghasilkan Wiki, Graph, Tree, PageIndex, Mind Map, Timeline, dan Skills pada tingkat dokumen dan dataset. +- 2026-08-19 Memperkenalkan Agentic RAG dengan mode berpikir Low, Medium, High, dan Ultra. +- 2026-07-02 Menambahkan ingest sumber data Google BigQuery dan sinkronisasi inkremental. +- 2026-06-29 Menambahkan kanal chat WhatsApp, DingTalk, dan WeCom. +- 2026-05-26 Menambahkan komponen Browser agar Agent dapat menjelajahi dan berinteraksi dengan halaman web. +- 2026-04-21 Menambahkan tujuh templat pipeline ingest data bawaan. +- 2026-04-21 Menambahkan publikasi aplikasi Agent, eksekusi kode sandbox, dan pembuatan grafik. +- 2026-04-21 Menambahkan penyimpanan dan pengambilan memori tingkat pengguna. + +Lihat [catatan rilis lengkap](./docs/release_notes.md) untuk pembaruan lainnya. ## 🎉 Tetap Terkini @@ -121,6 +117,21 @@ Coba layanan cloud kami di [https://cloud.ragflow.io](https://cloud.ragflow.io). - Cerdas dan dapat dijelaskan. - Banyak pilihan template yang tersedia. +### 🧩 **Kompilasi Pengetahuan (Knowledge Compilation)** + +- Ubah konten pada tingkat dokumen dan dataset menjadi artefak terstruktur seperti Wiki, Graph, Tree, PageIndex, Mind Map, Timeline, dan Skills. +- Atur model kompilasi serta aturan pemrosesan, lalu lihat, perbarui, atau buat ulang artefak pengetahuan. + +### 🧠 **Pengambilan Agentic (Agentic Retrieval)** + +- Model menganalisis pertanyaan kompleks dan bila perlu memecahnya, mencari pengetahuan, serta memverifikasi bukti melalui beberapa tahap. +- Mode Low, Medium, High, dan Ultra menyesuaikan kedalaman pencarian dan penalaran dengan kompleksitas pertanyaan. + +### ⚙️ **Arsitektur layanan native Go** + +- Satu layanan Go menyediakan API, Admin, Ingestor, dan Syncer. DeepDoc berjalan di dalam proses Go untuk analisis tata letak, OCR, dan pengenalan tabel. +- Layanan Go memanggil pustaka pengurai dokumen native dan ONNX Runtime melalui CGO. MCP dan Sandbox Executor dapat diaktifkan sesuai kebutuhan. + ### 🌱 **Referensi yang Didasarkan pada Data untuk Mengurangi Hallusinasi** - Visualisasi pemotongan teks memungkinkan intervensi manusia. @@ -140,24 +151,25 @@ Coba layanan cloud kami di [https://cloud.ragflow.io](https://cloud.ragflow.io). ## 🔎 Arsitektur Sistem
-RAGFlow system architecture +Arsitektur sistem RAGFlow
## 🎬 Pengelolaan Mandiri -### 📝 Prasyarat +### 🐳 Deployment Docker -- CPU >= 4 inti -- RAM >= 16 GB -- Disk >= 50 GB +#### 📝 Prasyarat Deployment Docker + +- Konfigurasi awal yang disarankan: 4 inti CPU, RAM 16 GB, dan ruang disk tersedia 50 GB. Kebutuhan aktual bergantung pada mesin dokumen, volume data, tugas penguraian, dan konkurensi. Model lokal dan komponen opsional lainnya mungkin memerlukan sumber daya tambahan. - Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- Python >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/): Hanya diperlukan jika Anda ingin menggunakan fitur eksekutor kode (sandbox) dari RAGFlow. +- [gVisor](https://gvisor.dev/docs/user_guide/install/): Hanya diperlukan saat menggunakan container Sandbox Self-Managed. + +Deployment Docker tidak memerlukan Go di host. Container Sandbox Self-Managed memerlukan instalasi dan konfigurasi gVisor; penyedia Sandbox lainnya tidak memerlukan gVisor di host RAGFlow. > [!TIP] > Jika Anda belum menginstal Docker di komputer lokal Anda (Windows, Mac, atau Linux), lihat [Install Docker Engine](https://docs.docker.com/engine/install/). -### 🚀 Menjalankan Server +#### 🚀 Menjalankan Server 1. Pastikan `vm.max_map_count` >= 262144: @@ -192,175 +204,109 @@ Coba layanan cloud kami di [https://cloud.ragflow.io](https://cloud.ragflow.io). > Semua gambar Docker dibangun untuk platform x86. Saat ini, kami tidak menawarkan gambar Docker untuk ARM64. > Jika Anda menggunakan platform ARM64, [silakan gunakan panduan ini untuk membangun gambar Docker yang kompatibel dengan sistem Anda](https://ragflow.io/docs/dev/build_docker_image). -> Perintah di bawah ini mengunduh edisi v0.27.2 dari gambar Docker RAGFlow. Silakan merujuk ke tabel berikut untuk deskripsi berbagai edisi RAGFlow. Untuk mengunduh edisi RAGFlow yang berbeda dari v0.27.2, perbarui variabel RAGFLOW_IMAGE di docker/.env sebelum menggunakan docker compose untuk memulai server. +> Tulis `RAGFLOW_IMAGE=ragflow:go-local` ke **docker/.env** sebelum memulai. Target build resmi image Go adalah `linux/amd64`. -```bash - cd ragflow/docker - - git checkout v0.27.2 - # Opsional: gunakan tag stabil (lihat releases: https://github.com/infiniflow/ragflow/releases) - # This steps ensures the **entrypoint.sh** file in the code matches the Docker image version. - - # Use CPU for DeepDoc tasks: - docker compose -f docker-compose.yml up -d - - # To use GPU to accelerate DeepDoc tasks: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d +```dotenv +RAGFLOW_IMAGE=ragflow:go-local ``` -> Catatan: Sebelum `v0.22.0`, kami menyediakan image dengan model embedding dan image slim tanpa model embedding. Detailnya sebagai berikut: +```bash +cd ragflow +docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . +cd docker +docker compose --env-file .env -f docker-compose.yml up -d +``` -| RAGFlow image tag | Image size (GB) | Has embedding models? | Stable? | -|-------------------|-----------------|-----------------------|----------------| -| v0.21.1 | ≈9 | ✔️ | Stable release | -| v0.21.1-slim | ≈2 | ❌ | Stable release | - -> Mulai dari `v0.22.0`, kami hanya menyediakan edisi slim dan tidak lagi menambahkan akhiran **-slim** pada tag image. +> Pada RAGFlow open-source 1.0, DeepDoc menggunakan inferensi CPU untuk analisis tata letak, OCR, dan pengenalan tabel. 1. Periksa status server setelah server aktif dan berjalan: ```bash - docker logs -f docker-ragflow-cpu-1 + docker compose --env-file .env -f docker-compose.yml ps + curl -f http://localhost/api/v1/system/healthz ``` - _Output berikut menandakan bahwa sistem berhasil diluncurkan:_ - - ```bash - - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) - ``` - - > Jika Anda melewatkan langkah ini dan langsung login ke RAGFlow, browser Anda mungkin menampilkan error `network abnormal` - > karena RAGFlow mungkin belum sepenuhnya siap. - > 2. Buka browser web Anda, masukkan alamat IP server Anda, dan login ke RAGFlow. > Dengan pengaturan default, Anda hanya perlu memasukkan `http://IP_DEVICE_ANDA` (**tanpa** nomor port) karena > port HTTP default `80` bisa dihilangkan saat menggunakan konfigurasi default. > -3. Dalam [service_conf.yaml.template](./docker/service_conf.yaml.template), pilih LLM factory yang diinginkan di `user_default_llm` dan perbarui - bidang `API_KEY` dengan kunci API yang sesuai. +3. Setelah masuk ke RAGFlow, tambahkan LLM, model embedding, dan reranker pada halaman penyedia model, lalu isi nama model, alamat layanan, dan API key yang sesuai. > Lihat [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup) untuk informasi lebih lanjut. > _Sistem telah siap digunakan!_ -## 🔧 Konfigurasi +#### ⚙️ Konfigurasi dan Penyesuaian Docker -Untuk konfigurasi sistem, Anda perlu mengelola file-file berikut: +Deployment Docker Go menggunakan `docker/.env` dan `docker/docker-compose.yml`, dengan Kvrocks untuk cache dan penyimpanan Checkpoint serta NATS JetStream sebagai antrean pesan. Untuk mengatur image, port, kata sandi, mesin dokumen, dan sumber image model, lihat [panduan konfigurasi Docker](./docker/README.md). Untuk batasan platform dan persyaratan macOS, lihat [panduan build image Go dan dukungan platform](./docs/develop/build_docker_image.mdx). -- [.env](./docker/.env): Menyimpan pengaturan dasar sistem, seperti `SVR_HTTP_PORT`, `MYSQL_PASSWORD`, dan - `MINIO_PASSWORD`. -- [service_conf.yaml.template](./docker/service_conf.yaml.template): Mengonfigurasi aplikasi backend. -- [docker-compose.yml](./docker/docker-compose.yml): Sistem ini bergantung pada [docker-compose.yml](./docker/docker-compose.yml) untuk memulai. +Untuk mengganti mesin dokumen, mengubah konfigurasi, memulai ulang layanan, serta mempertahankan atau menghapus data yang ada, ikuti juga panduan konfigurasi Docker tersebut. -Untuk memperbarui port HTTP default (80), buka [docker-compose.yml](./docker/docker-compose.yml) dan ubah `80:80` -menjadi `:80`. +### 🔨 Menjalankan Aplikasi dari Sumber untuk Pengembangan -Pembaruan konfigurasi ini memerlukan reboot semua kontainer agar efektif: +#### 📝 Prasyarat Build dari Sumber -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -## 🔧 Membangun Docker Image - -Image ini berukuran sekitar 2 GB dan bergantung pada aplikasi LLM eksternal dan embedding. - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -Jika berada di belakang proxy, Anda dapat melewatkan argumen proxy: - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 Menjalankan Aplikasi dari Sumber untuk Pengembangan - -1. Instal `uv`, atau lewati langkah ini jika sudah terinstal: - - ```bash - pipx install uv - ``` -2. Clone kode sumber dan instal dependensi Python: +1. Instal versi Go yang ditentukan di `go.mod` (saat ini Go 1.27), Clang 20, LLD 20, CMake 4.0 atau yang lebih baru, serta berkas pengembangan PCRE2. Layanan Go memerlukan CGO dan pustaka native; [build.sh](./build.sh) mengatur parameter build yang diperlukan. +2. Clone repositori, siapkan pustaka native dan berkas model yang diperlukan, lalu build layanan Go: ```bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/ - uv sync --python 3.13 # install RAGFlow dependent python modules - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` -3. Jalankan aplikasi yang diperlukan (MinIO, Elasticsearch, Redis, dan MySQL) menggunakan Docker Compose: + + Skrip tersebut menyiapkan pustaka native dan sumber daya model yang diperlukan untuk build Go serta memerlukan `requests` dan `huggingface-hub`. Lewati langkah ini jika sumber daya yang sama telah disiapkan dengan cara lain. Saat dijalankan dari root repositori, layanan Go otomatis menemukan `rag/res/deepdoc`; untuk menjalankan dari direktori lain, atur `DEEPDOC_MODEL_DIR` ke path absolutnya. +3. Jalankan dependensi yang diperlukan (Elasticsearch, MySQL, MinIO, NATS, Kvrocks, dan ClickHouse) menggunakan Docker Compose: ```bash - docker compose -f docker/docker-compose-base.yml up -d + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` - Tambahkan baris berikut ke `/etc/hosts` untuk memetakan semua host yang ditentukan di **conf/service_conf.yaml** ke `127.0.0.1`: + Layanan Go yang dijalankan dari sumber terhubung ke Kvrocks melalui `localhost:6379`; konfigurasi yang disediakan tidak memerlukan perubahan pada `/etc/hosts`. - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. Jika Anda tidak dapat mengakses HuggingFace, atur variabel lingkungan `HF_ENDPOINT` untuk menggunakan situs mirror: +4. Setelah migrasi database selesai, jalankan layanan secara berurutan. Jalankan setiap perintah di terminal terpisah dari root repositori dan biarkan keempat terminal layanan tetap berjalan: ```bash - export HF_ENDPOINT=https://hf-mirror.com + ./bin/ragflow_server --migrate + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api ``` -5. Jika sistem operasi Anda tidak memiliki jemalloc, instal sebagai berikut: - ```bash - # ubuntu - sudo apt-get install libjemalloc-dev - # centos - sudo yum install jemalloc - # mac - brew install jemalloc - ``` -6. Jalankan aplikasi backend: + Mode startup bekerja sebagai berikut: - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh - ``` -7. Instal dependensi frontend: + - `--migrate`: Menjalankan migrasi database lalu keluar. + - `--admin`: Memulai layanan Admin untuk pengelolaan dan inisialisasi. + - `--ingestor`: Memulai layanan Ingestor untuk tugas ingestion dan parsing data. + - `--syncer`: Memulai layanan Syncer untuk sinkronisasi data. + - `--api`: Memulai layanan API untuk Web UI, SDK, dan klien eksternal. + + `RAGFLOW_DEV_MODE=true` hanya untuk pengembangan; variabel ini menonaktifkan pemeriksaan downgrade antara versi kode dan migrasi database, tetapi tidak menjalankan migrasi atau mengubah skema. Jangan gunakan di produksi. Jalankan Admin sebelum layanan lain. Setelah migrasi, `RAGFLOW_DEV_MODE=true bash build.sh --run` memulai Admin, Ingestor, dan API, tetapi tidak memulai Syncer; jalankan Syncer secara terpisah dengan `RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer` untuk rantai layanan lengkap. +5. Hanya untuk pengembangan frontend, instal Node.js dan npm, lalu jalankan frontend React: ```bash cd web npm install + API_PROXY_SCHEME=go npm run dev ``` -8. Jalankan aplikasi frontend: + + Di terminal lain, pastikan Go API siap: ```bash - npm run dev + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` - _Output berikut menandakan bahwa sistem berhasil diluncurkan:_ + Respons HTTP 200 menunjukkan bahwa API merespons. Setelah pengembangan selesai, tekan `Ctrl+C` di setiap terminal layanan. Untuk menghentikan dependensi tanpa menghapus kontainer, jalankan `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse`. Untuk menghapus kontainer dependensi dan jaringan Compose sambil mempertahankan volume bernama, jalankan `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`. - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) -9. Hentikan layanan front-end dan back-end RAGFlow setelah pengembangan selesai: - - ```bash - pkill -f "ragflow_server.py|task_executor.py" - ``` +Lihat [Menjalankan Layanan dari Sumber](./docs/develop/launch_ragflow_from_source.md) untuk detailnya. ## 📚 Dokumentasi diff --git a/README_ja.md b/README_ja.md index 775b7ea7c1..bd726c67c2 100644 --- a/README_ja.md +++ b/README_ja.md @@ -26,7 +26,7 @@ Static Badge - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Latest Release @@ -34,9 +34,6 @@ license - - Ask DeepWiki -

@@ -62,6 +59,8 @@ 当社のクラウドサービスをぜひお試しください：[https://cloud.ragflow.io](https://cloud.ragflow.io)。 +ローカルにデプロイする場合は、[セルフホスティング](#-セルフホスティング)を参照してください。 +
Chunking demonstration Agentic workflow demonstration @@ -69,18 +68,17 @@ ## 🔥 最新情報 -- 2026-06-15 Feishu、Discord、Telegram、Lineなどの複数のチャットチャンネルをサポートします。 -- 2026-04-24 DeepSeek v4 をサポート。 -- 2026-03-24 [RAGFlow Skill on OpenClaw](https://clawhub.ai/yingfeng/ragflow-skill) — OpenClaw経由でRAGFlowデータセットにアクセスする公式スキルを提供。 -- 2025-12-26 AIエージェントの「メモリ」機能をサポート。 -- 2025-11-19 Gemini 3 Proをサポートしています。 -- 2025-11-12 Confluence、S3、Notion、Discord、Google Drive からのデータ同期をサポートします。 -- 2025-10-23 ドキュメント解析方法として MinerU と Docling をサポートします。 -- 2025-10-15 オーケストレーションされたデータパイプラインのサポート。 -- 2025-08-08 OpenAI の最新 GPT-5 シリーズモデルをサポートします。 -- 2025-08-01 エージェントワークフローとMCPをサポート。 -- 2025-05-23 エージェントに Python/JS コードエグゼキュータコンポーネントを追加しました。 -- 2025-03-19 PDFまたはDOCXファイル内の画像を理解するために、多モーダルモデルを使用することをサポートします。 +- 2026-09-10 SitemapによるWebコンテンツの取り込みに対応。 +- 2026-08-19 Knowledge Compilationを導入。ドキュメントおよびデータセット単位でWiki、Graph、Tree、PageIndex、Mind Map、Timeline、Skillsを生成できます。 +- 2026-08-19 Low、Medium、High、Ultraの思考モードを備えたAgentic RAGを導入。 +- 2026-07-02 Google BigQueryデータソースの取り込みと増分同期に対応。 +- 2026-06-29 WhatsApp、DingTalk、WeComのチャットチャネルに対応。 +- 2026-05-26 AgentがWebページを閲覧・操作できるBrowserコンポーネントを追加。 +- 2026-04-21 7種類の組み込みデータ取り込みパイプラインテンプレートを追加。 +- 2026-04-21 Agentアプリの公開、Sandboxでのコード実行、グラフ生成に対応。 +- 2026-04-21 ユーザー単位のメモリ保存と検索に対応。 + +その他の更新については[リリースノート全文](./docs/release_notes.md)を参照してください。 ## 🎉 続きを楽しみに @@ -95,7 +93,7 @@ ### 🍭 **"Quality in, quality out"** -- 複雑な形式の非構造化データからの[深い文書理解](./deepdoc/README.md)ベースの知識抽出。 +- 複雑な形式の非構造化データからの深い文書理解ベースの知識抽出。 - 無限のトークンから"干し草の山の中の針"を見つける。 ### 🍱 **テンプレートベースのチャンク化** @@ -103,6 +101,21 @@ - 知的で解釈しやすい。 - テンプレートオプションが豊富。 +### 🧩 **ナレッジコンパイル（Knowledge Compilation）** + +- ドキュメントやデータセットのコンテンツを、Wiki、Graph、Tree、PageIndex、Mind Map、Timeline、Skills などの構造化された成果物に整理します。 +- コンパイルモデルと処理ルールを設定し、成果物の表示、更新、再生成を行えます。 + +### 🧠 **Agentic Retrieval** + +- 複雑な質問を分析し、必要に応じて分解、ナレッジ検索、根拠確認を複数段階で行います。 +- Low、Medium、High、Ultra の思考モードで、質問の複雑さに応じて検索と推論の深さを調整できます。 + +### ⚙️ **Go ネイティブサービスアーキテクチャ** + +- API、Admin、Ingestor、Syncer は統合された Go サービスが提供します。DeepDoc は Go プロセス内で動作し、レイアウト解析、OCR、表認識を担当します。 +- Go サービスは CGO 経由でネイティブ文書解析ライブラリと ONNX Runtime を呼び出します。MCP と Sandbox Executor は必要に応じて有効化できます。 + ### 🌱 **ハルシネーションが軽減された根拠のある引用** - 可視化されたテキストチャンキング（text chunking）で人間の介入を可能にする。 @@ -122,24 +135,25 @@ ## 🔎 システム構成
-RAGFlow system architecture +RAGFlow システムアーキテクチャ
## 🎬 セルフホスティング -### 📝 必要条件 +### 🐳 Docker デプロイ -- CPU >= 4 cores -- RAM >= 16 GB -- Disk >= 50 GB +#### 📝 Docker デプロイの前提条件 + +- 推奨する開始時の構成：CPU 4コア、RAM 16 GB、空きディスク容量 50 GB。実際の要件は、ドキュメントエンジン、データ量、解析タスク、同時実行数によって異なります。ローカルモデルやその他のオプションコンポーネントでは、追加のリソースが必要になる場合があります。 - Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- Python >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/): RAGFlowのコード実行（サンドボックス）機能を利用する場合のみ必要です。 +- [gVisor](https://gvisor.dev/docs/user_guide/install/): Self-ManagedコンテナSandboxを使用する場合のみ必要です。 + +DockerデプロイではホストへのGoのインストールは不要です。Self-ManagedコンテナSandboxではgVisorのインストールと設定が必要ですが、他のSandboxプロバイダーではRAGFlowホストへのgVisorのインストールは不要です。 > [!TIP] > ローカルマシン（Windows、Mac、または Linux）に Docker をインストールしていない場合は、[Docker Engine のインストール](https://docs.docker.com/engine/install/) を参照してください。 -### 🚀 サーバーを起動 +#### 🚀 サーバーを起動 1. `vm.max_map_count` >= 262144 であることを確認する: @@ -173,195 +187,108 @@ > 現在、公式に提供されているすべての Docker イメージは x86 アーキテクチャ向けにビルドされており、ARM64 用の Docker イメージは提供されていません。 > ARM64 アーキテクチャのオペレーティングシステムを使用している場合は、[このドキュメント](https://ragflow.io/docs/dev/build_docker_image)を参照して Docker イメージを自分でビルドしてください。 -> 以下のコマンドは、RAGFlow Docker イメージの v0.27.2 エディションをダウンロードします。異なる RAGFlow エディションの説明については、以下の表を参照してください。v0.27.2 とは異なるエディションをダウンロードするには、docker/.env ファイルの RAGFLOW_IMAGE 変数を適宜更新し、docker compose を使用してサーバーを起動してください。 +> 起動前に **docker/.env** へ `RAGFLOW_IMAGE=ragflow:go-local` を設定してください。Go イメージの正式なビルド対象は `linux/amd64` です。 -```bash - cd ragflow/docker - - git checkout v0.27.2 - # 任意: 安定版タグを利用 (一覧: https://github.com/infiniflow/ragflow/releases) - # この手順は、コード内の entrypoint.sh ファイルが Docker イメージのバージョンと一致していることを確認します。 - - # Use CPU for DeepDoc tasks: - docker compose -f docker-compose.yml up -d - - # To use GPU to accelerate DeepDoc tasks: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d +```dotenv +RAGFLOW_IMAGE=ragflow:go-local ``` -> 注意：`v0.22.0` より前のバージョンでは、embedding モデルを含むイメージと、embedding モデルを含まない slim イメージの両方を提供していました。詳細は以下の通りです： + ```bash + cd ragflow + docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . + cd docker + docker compose --env-file .env -f docker-compose.yml up -d + ``` -| RAGFlow image tag | Image size (GB) | Has embedding models? | Stable? | -|-------------------|-----------------|-----------------------|----------------| -| v0.21.1 | ≈9 | ✔️ | Stable release | -| v0.21.1-slim | ≈2 | ❌ | Stable release | - -> `v0.22.0` 以降、当プロジェクトでは slim エディションのみを提供し、イメージタグに **-slim** サフィックスを付けなくなりました。 +> RAGFlow オープンソース 1.0 の DeepDoc は、レイアウト解析、OCR、表認識に CPU 推論を使用します。 1. サーバーを立ち上げた後、サーバーの状態を確認する: ```bash - docker logs -f docker-ragflow-cpu-1 + docker compose --env-file .env -f docker-compose.yml ps + curl -f http://localhost/api/v1/system/healthz ``` - _以下の出力は、システムが正常に起動したことを確認するものです:_ - - ```bash - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) - ``` - - > もし確認ステップをスキップして直接 RAGFlow にログインした場合、その時点で RAGFlow が完全に初期化されていない可能性があるため、ブラウザーがネットワーク異常エラーを表示するかもしれません。 - > 2. ウェブブラウザで、プロンプトに従ってサーバーの IP アドレスを入力し、RAGFlow にログインします。 > デフォルトの設定を使用する場合、デフォルトの HTTP サービングポート `80` は省略できるので、与えられたシナリオでは、`http://IP_OF_YOUR_MACHINE`（ポート番号は省略）だけを入力すればよい。 > -3. [service_conf.yaml.template](./docker/service_conf.yaml.template) で、`user_default_llm` で希望の LLM ファクトリを選択し、`API_KEY` フィールドを対応する API キーで更新する。 +3. RAGFlow にログインした後、モデルプロバイダーページで LLM、Embedding、Reranker を追加し、モデル名、サービスアドレス、API キーを入力します。 > 詳しくは [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup) を参照してください。 > _これで初期設定完了！ショーの開幕です！_ -## 🔧 コンフィグ +#### ⚙️ Docker の設定と調整 -システムコンフィグに関しては、以下のファイルを管理する必要がある: +Go版のDockerデプロイでは `docker/.env` と `docker/docker-compose.yml` を使用し、キャッシュとCheckpointの保存にKvrocks、メッセージキューにNATS JetStreamを使用します。イメージ、ポート、パスワード、ドキュメントエンジン、モデルイメージの取得元を変更する場合は、[Docker設定ガイド](./docker/README.md)に従ってください。プラットフォームの制限とmacOSの要件については、[Go Dockerイメージのビルドとプラットフォームサポートガイド](./docs/develop/build_docker_image.mdx)を参照してください。 -- [.env](./docker/.env): `SVR_HTTP_PORT`、`MYSQL_PASSWORD`、`MINIO_PASSWORD` などのシステムの基本設定を保持する。 -- [service_conf.yaml.template](./docker/service_conf.yaml.template): バックエンドのサービスを設定します。 -- [docker-compose.yml](./docker/docker-compose.yml): システムの起動は [docker-compose.yml](./docker/docker-compose.yml) に依存している。 +ドキュメントエンジンの切り替え、設定変更後のサービス再起動、既存データの保持または削除についても、上記のDocker設定ガイドに従ってください。 -[.env](./docker/.env) ファイルの変更が [service_conf.yaml.template](./docker/service_conf.yaml.template) ファイルの内容と一致していることを確認する必要があります。 +### 🔨 ソースコードからサービスを起動する方法 -> [./docker/README](./docker/README.md) ファイル ./docker/README には、service_conf.yaml.template ファイルで ${ENV_VARS} として使用できる環境設定とサービス構成の詳細な説明が含まれています。 +#### 📝 ソースビルドの前提条件 -デフォルトの HTTP サービングポート(80)を更新するには、[docker-compose.yml](./docker/docker-compose.yml) にアクセスして、`80:80` を `:80` に変更します。 - -> すべてのシステム設定のアップデートを有効にするには、システムの再起動が必要です: -> -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -### Elasticsearch から Infinity にドキュメントエンジンを切り替えます - -RAGFlow はデフォルトで Elasticsearch を使用して全文とベクトルを保存します。［Infinity］に切り替え（https://github.com/infiniflow/infinity/)、次の手順に従います。 - -1. 実行中のすべてのコンテナを停止するには： - - ```bash - docker compose -f docker/docker-compose.yml down -v - ``` - - Note: `-v` は docker コンテナのボリュームを削除し、既存のデータをクリアします。 -2. **docker/.env** の「DOC \_ ENGINE」を「infinity」に設定します。 -3. 起動コンテナ： - - ```bash - docker compose -f docker/docker-compose.yml up -d - ``` - - > [!WARNING] - > Linux/arm64 マシンでの Infinity への切り替えは正式にサポートされていません。 - > - -## 🔧 ソースコードで Docker イメージを作成 - -この Docker イメージのサイズは約 1GB で、外部の大モデルと埋め込みサービスに依存しています。 - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -プロキシ環境下にいる場合は、プロキシ引数を指定できます： - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 ソースコードからサービスを起動する方法 - -1. `uv` をインストールする。すでにインストールされている場合は、このステップをスキップしてください: - - ```bash - pipx install uv - ``` -2. ソースコードをクローンし、Python の依存関係をインストールする: +1. `go.mod` で指定されたGoバージョン（現在はGo 1.27）、Clang 20、LLD 20、CMake 4.0以降、およびPCRE2開発ファイルをインストールします。GoサービスはCGOとネイティブライブラリに依存し、[build.sh](./build.sh)が必要なビルド設定を行います。 +2. リポジトリをクローンし、必要なネイティブライブラリとモデルファイルを準備してからGoサービスをビルドします: ```bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/ - uv sync --python 3.13 # install RAGFlow dependent python modules - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` -3. Docker Compose を使用して依存サービス（MinIO、Elasticsearch、Redis、MySQL）を起動する: + + このスクリプトはGoビルドに必要なネイティブライブラリとモデルリソースを準備し、`requests`と`huggingface-hub`を使用します。同じリソースを別の方法で準備済みの場合は、この手順を省略できます。リポジトリルートから起動するとGoサービスは`rag/res/deepdoc`を自動検出します。別のディレクトリから起動する場合は、`DEEPDOC_MODEL_DIR`にその絶対パスを設定してください。 +3. Docker Composeで必要な依存サービス（Elasticsearch、MySQL、MinIO、NATS、Kvrocks、ClickHouse）を起動します: ```bash - docker compose -f docker/docker-compose-base.yml up -d + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` - `/etc/hosts` に以下の行を追加して、**conf/service_conf.yaml** に指定されたすべてのホストを `127.0.0.1` に解決します: + ソースから起動する Go サービスは `localhost:6379` で Kvrocks に接続するため、提供されている設定では `/etc/hosts` の変更は不要です。 - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. HuggingFace にアクセスできない場合は、`HF_ENDPOINT` 環境変数を設定してミラーサイトを使用してください: +4. データベースのマイグレーション後、サービスを順番に起動します。各コマンドはリポジトリのルートから別々のターミナルで実行し、サービス用の4つのターミナルは開いたままにします: ```bash - export HF_ENDPOINT=https://hf-mirror.com + ./bin/ragflow_server --migrate + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api ``` -5. オペレーティングシステムにjemallocがない場合は、次のようにインストールします: - ```bash - # ubuntu - sudo apt-get install libjemalloc-dev - # centos - sudo yum install jemalloc - # mac - brew install jemalloc - ``` -6. バックエンドサービスを起動する: + 各起動モードの役割は次のとおりです: - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh - ``` -7. フロントエンドの依存関係をインストールする: + - `--migrate`: データベース移行を実行して終了します。 + - `--admin`: 管理と初期化を行うAdminサービスを起動します。 + - `--ingestor`: データ取り込みと解析を行うIngestorサービスを起動します。 + - `--syncer`: データ同期を行うSyncerサービスを起動します。 + - `--api`: Web UI、SDK、外部クライアント向けのAPIサービスを起動します。 + + `RAGFLOW_DEV_MODE=true`は開発専用です。コードとデータベース移行バージョン間のダウングレードチェックを無効にしますが、移行の実行やスキーマ変更は行いません。本番環境では設定しないでください。Adminを他のサービスより先に起動します。移行後は`RAGFLOW_DEV_MODE=true bash build.sh --run`でAdmin、Ingestor、APIを起動できますが、Syncerは起動しません。完全なサービスチェーンには`RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer`を別途実行してください。 +5. フロントエンドを開発する場合に限り、Node.jsとnpmをインストールしてReactフロントエンドを起動します: ```bash cd web npm install + API_PROXY_SCHEME=go npm run dev ``` -8. フロントエンドサービスを起動する: + + 別のターミナルでGo APIの準備が完了したことを確認します: ```bash - npm run dev + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` - _以下の画面で、システムが正常に起動したことを示します:_ + HTTP 200が返ればAPIは応答しています。開発終了時は各サービスターミナルで`Ctrl+C`を押します。コンテナを保持したまま依存サービスを停止するには `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse` を実行します。名前付きボリュームを保持したまま依存コンテナとComposeネットワークを削除するには `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down` を実行します。 - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) -9. 開発が完了したら、RAGFlow のフロントエンド サービスとバックエンド サービスを停止します: - - ```bash - pkill -f "ragflow_server.py|task_executor.py" - ``` +詳細は[ソースコードからサービスを起動](./docs/develop/launch_ragflow_from_source.md)を参照してください。 ## 📚 ドキュメンテーション diff --git a/README_ko.md b/README_ko.md index 10d1ac1556..c9d8bd67af 100644 --- a/README_ko.md +++ b/README_ko.md @@ -26,7 +26,7 @@ Static Badge - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Latest Release @@ -34,9 +34,6 @@ license - - Ask DeepWiki -

@@ -63,6 +60,8 @@ [https://cloud.ragflow.io](https://cloud.ragflow.io)에서 저희 클라우드 서비스를 이용해 보세요. +로컬 배포는 [자체 호스팅](#-자체-호스팅)을 참조하세요. +
Chunking demonstration Agentic workflow demonstration @@ -70,18 +69,17 @@ ## 🔥 업데이트 -- 2026-06-15 Feishu, Discord, Telegram, Line 등 다양한 채팅 채널을 지원합니다. -- 2026-04-24 DeepSeek v4를 지원합니다. -- 2026-03-24 [RAGFlow Skill on OpenClaw](https://clawhub.ai/yingfeng/ragflow-skill) — OpenClaw를 통해 RAGFlow 데이터셋에 접근하는 공식 스킬 제공. -- 2025-12-26 AI 에이전트의 '메모리' 기능 지원. -- 2025-11-19 Gemini 3 Pro를 지원합니다. -- 2025-11-12 Confluence, S3, Notion, Discord, Google Drive에서 데이터 동기화를 지원합니다. -- 2025-10-23 문서 파싱 방법으로 MinerU 및 Docling을 지원합니다. -- 2025-10-15 조정된 데이터 파이프라인 지원. -- 2025-08-08 OpenAI의 최신 GPT-5 시리즈 모델을 지원합니다. -- 2025-08-01 에이전트 워크플로우와 MCP를 지원합니다. -- 2025-05-23 Agent에 Python/JS 코드 실행기 구성 요소를 추가합니다. -- 2025-03-19 PDF 또는 DOCX 파일 내의 이미지를 이해하기 위해 다중 모드 모델을 사용하는 것을 지원합니다. +- 2026-09-10 사이트맵을 통한 웹 콘텐츠 수집을 추가했습니다. +- 2026-08-19 Knowledge Compilation을 도입했습니다. 문서 및 데이터셋 수준에서 Wiki, Graph, Tree, PageIndex, Mind Map, Timeline, Skills를 생성할 수 있습니다. +- 2026-08-19 Low, Medium, High, Ultra 사고 모드를 지원하는 Agentic RAG를 도입했습니다. +- 2026-07-02 Google BigQuery 데이터 소스 수집 및 증분 동기화를 추가했습니다. +- 2026-06-29 WhatsApp, DingTalk, WeCom 채팅 채널을 추가했습니다. +- 2026-05-26 Agent가 웹 페이지를 탐색하고 조작할 수 있는 Browser 구성 요소를 추가했습니다. +- 2026-04-21 기본 제공 데이터 수집 파이프라인 템플릿 7종을 추가했습니다. +- 2026-04-21 Agent 애플리케이션 게시, Sandbox 코드 실행, 차트 생성을 추가했습니다. +- 2026-04-21 사용자 수준 메모리 저장 및 검색을 추가했습니다. + +자세한 내용은 [전체 릴리스 노트](./docs/release_notes.md)를 참조하세요. ## 🎉 계속 지켜봐 주세요 @@ -96,7 +94,7 @@ ### 🍭 **"Quality in, quality out"** -- [심층 문서 이해](./deepdoc/README.md)를 기반으로 복잡한 형식의 비정형 데이터에서 지식을 추출합니다. +- 심층 문서 이해를 기반으로 복잡한 형식의 비정형 데이터에서 지식을 추출합니다. - 문자 그대로 무한한 토큰에서 "데이터 속의 바늘"을 찾아냅니다. ### 🍱 **템플릿 기반의 chunking** @@ -104,6 +102,21 @@ - 똑똑하고 설명 가능한 방식. - 다양한 템플릿 옵션을 제공합니다. +### 🧩 **지식 컴파일(Knowledge Compilation)** + +- 문서와 데이터셋의 콘텐츠를 Wiki, Graph, Tree, PageIndex, Mind Map, Timeline, Skills 등의 구조화된 지식 산출물로 정리합니다. +- 컴파일 모델과 처리 규칙을 설정하고 산출물을 확인, 업데이트, 재생성할 수 있습니다. + +### 🧠 **Agentic Retrieval** + +- 복잡한 질문을 분석하고 필요하면 여러 단계로 질문을 분해하고 지식을 검색하며 근거를 검증합니다. +- Low, Medium, High, Ultra 사고 모드로 질문 복잡도에 따라 검색 및 추론 깊이를 조절할 수 있습니다. + +### ⚙️ **Go 네이티브 서비스 아키텍처** + +- 통합 Go 서비스가 API, Admin, Ingestor, Syncer를 제공합니다. DeepDoc은 Go 프로세스 안에서 레이아웃 분석, OCR, 표 인식을 수행합니다. +- Go 서비스는 CGO를 통해 네이티브 문서 파싱 라이브러리와 ONNX Runtime을 호출합니다. MCP와 Sandbox Executor는 필요할 때 활성화할 수 있습니다. + ### 🌱 **할루시네이션을 줄인 신뢰할 수 있는 인용** - 텍스트 청킹을 시각화하여 사용자가 개입할 수 있도록 합니다. @@ -123,24 +136,25 @@ ## 🔎 시스템 아키텍처
-RAGFlow system architecture +RAGFlow 시스템 아키텍처
## 🎬 자체 호스팅 -### 📝 사전 준비 사항 +### 🐳 Docker 배포 -- CPU >= 4 cores -- RAM >= 16 GB -- Disk >= 50 GB +#### 📝 Docker 배포 사전 요구 사항 + +- 권장 시작 구성: CPU 4코어, RAM 16 GB, 사용 가능한 디스크 공간 50 GB. 실제 요구 사항은 문서 엔진, 데이터 양, 파싱 작업, 동시 실행 수에 따라 달라집니다. 로컬 모델과 기타 선택적 구성 요소에는 추가 리소스가 필요할 수 있습니다. - Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- Python >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/): RAGFlow의 코드 실행기(샌드박스) 기능을 사용하려는 경우에만 필요합니다. +- [gVisor](https://gvisor.dev/docs/user_guide/install/): Self-Managed 컨테이너 Sandbox를 사용하는 경우에만 필요합니다. + +Docker 배포에는 호스트에 Go를 설치할 필요가 없습니다. Self-Managed 컨테이너 Sandbox는 gVisor 설치와 설정이 필요하지만, 다른 Sandbox 공급자는 RAGFlow 호스트에 gVisor를 설치할 필요가 없습니다. > [!TIP] > 로컬 머신(Windows, Mac, Linux)에 Docker가 설치되지 않은 경우, [Docker 엔진 설치](https://docs.docker.com/engine/install/)를 참조하세요. -### 🚀 서버 시작하기 +#### 🚀 서버 시작하기 1. `vm.max_map_count`가 262144 이상인지 확인하세요: @@ -175,196 +189,108 @@ > 모든 Docker 이미지는 x86 플랫폼을 위해 빌드되었습니다. 우리는 현재 ARM64 플랫폼을 위한 Docker 이미지를 제공하지 않습니다. > ARM64 플랫폼을 사용 중이라면, [시스템과 호환되는 Docker 이미지를 빌드하려면 이 가이드를 사용해 주세요](https://ragflow.io/docs/dev/build_docker_image). - > 아래 명령어는 RAGFlow Docker 이미지의 v0.27.2 버전을 다운로드합니다. 다양한 RAGFlow 버전에 대한 설명은 다음 표를 참조하십시오. v0.27.2와 다른 RAGFlow 버전을 다운로드하려면, docker/.env 파일에서 RAGFLOW_IMAGE 변수를 적절히 업데이트한 후 docker compose를 사용하여 서버를 시작하십시오. + > 시작하기 전에 **docker/.env**에 `RAGFLOW_IMAGE=ragflow:go-local`을 설정하세요. Go 이미지의 공식 빌드 대상은 `linux/amd64`입니다. + + ```dotenv + RAGFLOW_IMAGE=ragflow:go-local + ``` ```bash - cd ragflow/docker + cd ragflow + docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . + cd docker + docker compose --env-file .env -f docker-compose.yml up -d + ``` - git checkout v0.27.2 - # Optional: use a stable tag (see releases: https://github.com/infiniflow/ragflow/releases) - # 이 단계는 코드의 entrypoint.sh 파일이 Docker 이미지 버전과 일치하도록 보장합니다. - - # Use CPU for DeepDoc tasks: - docker compose -f docker-compose.yml up -d - - # To use GPU to accelerate DeepDoc tasks: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d -``` - -> 참고: `v0.22.0` 이전 버전에서는 embedding 모델이 포함된 이미지와 embedding 모델이 포함되지 않은 slim 이미지를 모두 제공했습니다. 자세한 내용은 다음과 같습니다: - -| RAGFlow image tag | Image size (GB) | Has embedding models? | Stable? | -|-------------------|-----------------|-----------------------|----------------| -| v0.21.1 | ≈9 | ✔️ | Stable release | -| v0.21.1-slim | ≈2 | ❌ | Stable release | - -> `v0.22.0`부터는 slim 에디션만 배포하며 이미지 태그에 **-slim** 접미사를 더 이상 붙이지 않습니다. +> RAGFlow 오픈 소스 1.0의 DeepDoc은 레이아웃 분석, OCR, 표 인식에 CPU 추론을 사용합니다. 1. 서버가 시작된 후 서버 상태를 확인하세요: ```bash - docker logs -f docker-ragflow-cpu-1 + docker compose --env-file .env -f docker-compose.yml ps + curl -f http://localhost/api/v1/system/healthz ``` - _다음 출력 결과로 시스템이 성공적으로 시작되었음을 확인합니다:_ - - ```bash - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) - ``` - - > 만약 확인 단계를 건너뛰고 바로 RAGFlow에 로그인하면, RAGFlow가 완전히 초기화되지 않았기 때문에 브라우저에서 `network abnormal` 오류가 발생할 수 있습니다. - 2. 웹 브라우저에 서버의 IP 주소를 입력하고 RAGFlow에 로그인하세요. > 기본 설정을 사용할 경우, `http://IP_OF_YOUR_MACHINE`만 입력하면 됩니다 (포트 번호는 제외). 기본 HTTP 서비스 포트 `80`은 기본 구성으로 사용할 때 생략할 수 있습니다. -3. [service_conf.yaml.template](./docker/service_conf.yaml.template) 파일에서 원하는 LLM 팩토리를 `user_default_llm`에 선택하고, `API_KEY` 필드를 해당 API 키로 업데이트하세요. +3. RAGFlow에 로그인한 뒤 모델 공급자 페이지에서 LLM, 임베딩 모델, 리랭커를 추가하고 모델 이름, 서비스 주소, API 키를 입력하세요. > 자세한 내용은 [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup)를 참조하세요. _이제 쇼가 시작됩니다!_ -## 🔧 설정 +#### ⚙️ Docker 구성 및 조정 -시스템 설정과 관련하여 다음 파일들을 관리해야 합니다: +Go Docker 배포는 `docker/.env`와 `docker/docker-compose.yml`을 사용하며, 캐시와 Checkpoint 저장에는 Kvrocks를, 메시지 큐에는 NATS JetStream을 사용합니다. 이미지, 포트, 비밀번호, 문서 엔진, 모델 이미지 소스를 변경하려면 [Docker 구성 가이드](./docker/README.md)를 따르세요. 플랫폼 제한과 macOS 요구 사항은 [Go Docker 이미지 빌드 및 플랫폼 지원 가이드](./docs/develop/build_docker_image.mdx)를 참조하세요. -- [.env](./docker/.env): `SVR_HTTP_PORT`, `MYSQL_PASSWORD`, `MINIO_PASSWORD`와 같은 시스템의 기본 설정을 포함합니다. -- [service_conf.yaml.template](./docker/service_conf.yaml.template): 백엔드 서비스를 구성합니다. -- [docker-compose.yml](./docker/docker-compose.yml): 시스템은 [docker-compose.yml](./docker/docker-compose.yml)을 사용하여 시작됩니다. +문서 엔진 전환, 구성 변경 후 서비스 재시작, 기존 데이터 보존 또는 삭제 작업도 위 Docker 구성 가이드를 따르세요. -[.env](./docker/.env) 파일의 변경 사항이 [service_conf.yaml.template](./docker/service_conf.yaml.template) 파일의 내용과 일치하도록 해야 합니다. +### 🔨 소스 코드로 서비스를 시작합니다. -> [./docker/README](./docker/README.md) 파일 ./docker/README은 service_conf.yaml.template 파일에서 ${ENV_VARS}로 사용할 수 있는 환경 설정과 서비스 구성에 대한 자세한 설명을 제공합니다. +#### 📝 소스 빌드 사전 요구 사항 -기본 HTTP 서비스 포트(80)를 업데이트하려면 [docker-compose.yml](./docker/docker-compose.yml) 파일에서 `80:80`을 `:80`으로 변경하세요. +1. `go.mod`에 지정된 Go 버전(현재 Go 1.27), Clang 20, LLD 20, CMake 4.0 이상, PCRE2 개발 파일을 설치합니다. Go 서비스는 CGO와 네이티브 라이브러리에 의존하며 [build.sh](./build.sh)가 필요한 빌드 매개변수를 설정합니다. -> 모든 시스템 구성 업데이트는 적용되기 위해 시스템 재부팅이 필요합니다. -> -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -### Elasticsearch 에서 Infinity 로 문서 엔진 전환 - -RAGFlow 는 기본적으로 Elasticsearch 를 사용하여 전체 텍스트 및 벡터를 저장합니다. [Infinity]로 전환(https://github.com/infiniflow/infinity/), 다음 절차를 따르십시오. - -1. 실행 중인 모든 컨테이너를 중지합니다. - ```bash - $docker compose-f docker/docker-compose.yml down -v - ``` - Note: `-v` 는 docker 컨테이너의 볼륨을 삭제하고 기존 데이터를 지우며, 이 작업은 컨테이너를 중지하는 것과 동일합니다. -2. **docker/.env**의 "DOC_ENGINE" 을 "infinity" 로 설정합니다. -3. 컨테이너 부팅: - ```bash - $docker compose-f docker/docker-compose.yml up -d - ``` - > [!WARNING] - > Linux/arm64 시스템에서 Infinity로 전환하는 것은 공식적으로 지원되지 않습니다. - -## 🔧 소스 코드로 Docker 이미지를 컴파일합니다 - -이 Docker 이미지의 크기는 약 1GB이며, 외부 대형 모델과 임베딩 서비스에 의존합니다. - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -프록시 환경인 경우, 프록시 인수를 전달할 수 있습니다： - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 소스 코드로 서비스를 시작합니다. - -1. `uv` 와 `pre-commit` 을 설치하거나, 이미 설치된 경우 이 단계를 건너뜁니다: - - ```bash - pipx install uv - ``` - -2. 소스 코드를 클론하고 Python 의존성을 설치합니다: +2. 저장소를 클론하고 빌드에 필요한 네이티브 라이브러리와 모델 파일을 준비한 뒤 Go 서비스를 빌드합니다: ```bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/ - uv sync --python 3.13 # install RAGFlow dependent python modules - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` -3. Docker Compose를 사용하여 의존 서비스(MinIO, Elasticsearch, Redis 및 MySQL)를 시작합니다: + 이 스크립트는 Go 빌드에 필요한 네이티브 라이브러리와 모델 리소스를 준비하며 `requests`와 `huggingface-hub`가 필요합니다. 같은 리소스를 다른 방법으로 준비했다면 이 단계를 건너뛸 수 있습니다. 저장소 루트에서 시작하면 Go 서비스가 `rag/res/deepdoc`을 자동으로 찾습니다. 다른 디렉터리에서 시작하려면 `DEEPDOC_MODEL_DIR`을 해당 디렉터리의 절대 경로로 설정하세요. + +3. Docker Compose를 사용하여 필요한 의존 서비스(Elasticsearch, MySQL, MinIO, NATS, Kvrocks, ClickHouse)를 시작합니다: ```bash - docker compose -f docker/docker-compose-base.yml up -d + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` - `/etc/hosts` 에 다음 줄을 추가하여 **conf/service_conf.yaml** 에 지정된 모든 호스트를 `127.0.0.1` 로 해결합니다: + 소스에서 실행하는 Go 서비스는 `localhost:6379`로 Kvrocks에 연결하므로 제공된 구성에서는 `/etc/hosts`를 수정할 필요가 없습니다. - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. HuggingFace에 접근할 수 없는 경우, `HF_ENDPOINT` 환경 변수를 설정하여 미러 사이트를 사용하세요: +4. 데이터베이스 마이그레이션 후 서비스를 순서대로 시작합니다. 각 명령은 저장소 루트에서 별도의 터미널로 실행하고, 네 개의 서비스 터미널을 계속 열어 둡니다: ```bash - export HF_ENDPOINT=https://hf-mirror.com + ./bin/ragflow_server --migrate + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api ``` -5. 만약 운영 체제에 jemalloc이 없으면 다음 방식으로 설치하세요: + 시작 모드의 역할은 다음과 같습니다: - ```bash - # ubuntu - sudo apt-get install libjemalloc-dev - # centos - sudo yum install jemalloc - # mac - brew install jemalloc - ``` + - `--migrate`: 데이터베이스 마이그레이션을 실행한 뒤 종료합니다. + - `--admin`: 관리 및 초기화 작업을 위한 Admin 서비스를 시작합니다. + - `--ingestor`: 데이터 수집 및 파싱 작업을 위한 Ingestor 서비스를 시작합니다. + - `--syncer`: 데이터 동기화 작업을 위한 Syncer 서비스를 시작합니다. + - `--api`: Web UI, SDK 및 외부 클라이언트를 위한 API 서비스를 시작합니다. -6. 백엔드 서비스를 시작합니다: - - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh - ``` - -7. 프론트엔드 의존성을 설치합니다: + `RAGFLOW_DEV_MODE=true`는 개발 전용입니다. 코드 버전과 데이터베이스 마이그레이션 버전 사이의 다운그레이드 검사를 비활성화하지만 마이그레이션을 실행하거나 스키마를 변경하지 않습니다. 프로덕션에서는 설정하지 마세요. Admin을 다른 서비스보다 먼저 시작하세요. 마이그레이션 후 `RAGFLOW_DEV_MODE=true bash build.sh --run`은 Admin, Ingestor, API를 시작하지만 Syncer는 시작하지 않습니다. 전체 서비스 체인에는 `RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer`를 별도로 실행하세요. +5. 프론트엔드를 개발할 때만 Node.js와 npm을 설치한 다음 React 프론트엔드를 시작합니다: ```bash cd web npm install + API_PROXY_SCHEME=go npm run dev ``` -8. 프론트엔드 서비스를 시작합니다: + 다른 터미널에서 Go API가 준비되었는지 확인합니다: ```bash - npm run dev + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` - _다음 인터페이스는 시스템이 성공적으로 시작되었음을 나타냅니다:_ + HTTP 200 응답은 API가 정상적으로 응답함을 의미합니다. 개발이 끝나면 각 서비스 터미널에서 `Ctrl+C`를 누릅니다. 컨테이너를 유지한 채 의존 서비스를 중지하려면 `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse`를 실행합니다. 명명된 볼륨을 유지하면서 의존 컨테이너와 Compose 네트워크를 삭제하려면 `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`을 실행합니다. - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) - - -9. 개발이 완료된 후 RAGFlow 프론트엔드 및 백엔드 서비스를 중지합니다. - - ```bash - pkill -f "ragflow_server.py|task_executor.py" - ``` +자세한 내용은 [소스에서 서비스 시작](./docs/develop/launch_ragflow_from_source.md)을 참조하세요. ## 📚 문서 diff --git a/README_pt_br.md b/README_pt_br.md index 75d65c7a65..305832e48f 100644 --- a/README_pt_br.md +++ b/README_pt_br.md @@ -26,7 +26,7 @@ Badge Estático - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Última Release @@ -34,9 +34,6 @@ licença - - Ask DeepWiki -

@@ -88,18 +85,17 @@ Experimente o nosso serviço na nuvem em [https://cloud.ragflow.io](https://clou ## 🔥 Últimas Atualizações -- 15-06-2026 Suporte a múltiplos canais de chat, como Feishu, Discord, Telegram, Line, etc.. -- 24-04-2026 Suporta DeepSeek v4. -- 24-03-2026 [RAGFlow Skill on OpenClaw](https://clawhub.ai/yingfeng/ragflow-skill) — Fornece um skill oficial para acessar datasets do RAGFlow via OpenClaw. -- 26-12-2025 Suporte à função 'Memória' para agentes de IA. -- 19-11-2025 Suporta Gemini 3 Pro. -- 12-11-2025 Suporta a sincronização de dados do Confluence, S3, Notion, Discord e Google Drive. -- 23-10-2025 Suporta MinerU e Docling como métodos de análise de documentos. -- 15-10-2025 Suporte para pipelines de dados orquestrados. -- 08-08-2025 Suporta a mais recente série GPT-5 da OpenAI. -- 01-08-2025 Suporta fluxo de trabalho agente e MCP. -- 23-05-2025 Adicione o componente executor de código Python/JS ao Agente. -- 19-03-2025 Suporta o uso de um modelo multi-modal para entender imagens dentro de arquivos PDF ou DOCX. +- 2026-09-10 Adicionada a ingestão de conteúdo da Web por meio de sitemaps. +- 2026-08-19 Lançado o Knowledge Compilation, que gera Wikis, Graphs, Trees, PageIndex, Mind Maps, Timelines e Skills nos níveis de documento e dataset. +- 2026-08-19 Lançado o Agentic RAG com os modos de pensamento Low, Medium, High e Ultra. +- 2026-07-02 Adicionadas a ingestão de dados do Google BigQuery e a sincronização incremental. +- 2026-06-29 Adicionados canais de chat para WhatsApp, DingTalk e WeCom. +- 2026-05-26 Adicionado o componente Browser, que permite aos Agents navegar e interagir com páginas da Web. +- 2026-04-21 Adicionados sete modelos integrados de pipeline de ingestão de dados. +- 2026-04-21 Adicionadas a publicação de aplicações Agent, a execução de código em sandbox e a geração de gráficos. +- 2026-04-21 Adicionados o armazenamento e a recuperação de memória em nível de usuário. + +Consulte as [notas de versão completas](./docs/release_notes.md) para ver outras atualizações. ## 🎉 Fique Ligado @@ -113,7 +109,7 @@ Experimente o nosso serviço na nuvem em [https://cloud.ragflow.io](https://clou ### 🍭 **"Qualidade entra, qualidade sai"** -- Extração de conhecimento baseada em [entendimento profundo de documentos](./deepdoc/README.md) a partir de dados não estruturados com formatos complicados. +- Extração de conhecimento baseada em entendimento profundo de documentos a partir de dados não estruturados com formatos complicados. - Encontra a "agulha no palheiro de dados" de literalmente tokens ilimitados. ### 🍱 **Fragmentação baseada em templates** @@ -121,6 +117,21 @@ Experimente o nosso serviço na nuvem em [https://cloud.ragflow.io](https://clou - Inteligente e explicável. - Muitas opções de templates para escolher. +### 🧩 **Compilação de conhecimento (Knowledge Compilation)** + +- Organize conteúdo de documentos e conjuntos de dados em artefatos estruturados, como Wiki, Graph, Tree, PageIndex, Mind Map, Timeline e Skills. +- Configure modelos de compilação e regras de processamento e visualize, atualize ou gere novamente os artefatos. + +### 🧠 **Recuperação agêntica (Agentic Retrieval)** + +- O modelo analisa perguntas complexas e, quando necessário, divide a questão, pesquisa conhecimentos e verifica evidências em várias etapas. +- Os modos Low, Medium, High e Ultra permitem ajustar a profundidade da busca e do raciocínio à complexidade da pergunta. + +### ⚙️ **Arquitetura de serviços nativa em Go** + +- Um serviço Go unificado fornece API, Admin, Ingestor e Syncer. O DeepDoc é executado no processo Go e realiza análise de layout, OCR e reconhecimento de tabelas. +- Os serviços Go chamam bibliotecas nativas de análise de documentos e ONNX Runtime via CGO. MCP e Sandbox Executor podem ser habilitados conforme necessário. + ### 🌱 **Citações fundamentadas com menos alucinações** - Visualização da fragmentação de texto para permitir intervenção humana. @@ -140,24 +151,25 @@ Experimente o nosso serviço na nuvem em [https://cloud.ragflow.io](https://clou ## 🔎 Arquitetura do Sistema
-RAGFlow system architecture +Arquitetura do sistema RAGFlow
## 🎬 Auto-hospedagem -### 📝 Pré-requisitos +### 🐳 Implantação com Docker -- CPU >= 4 núcleos -- RAM >= 16 GB -- Disco >= 50 GB +#### 📝 Pré-requisitos da implantação com Docker + +- Configuração inicial recomendada: 4 núcleos de CPU, 16 GB de RAM e 50 GB de espaço em disco disponível. Os requisitos reais dependem do mecanismo de documentos, volume de dados, tarefas de análise e concorrência. Modelos locais e outros componentes opcionais podem exigir recursos adicionais. - Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- Python >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/): Necessário apenas se você pretende usar o recurso de executor de código (sandbox) do RAGFlow. +- [gVisor](https://gvisor.dev/docs/user_guide/install/): Necessário somente ao usar o Sandbox de contêineres Self-Managed. + +A implantação Docker não exige a instalação do Go no host. O Sandbox de contêineres Self-Managed exige instalação e configuração do gVisor; outros provedores de Sandbox não exigem gVisor no host do RAGFlow. > [!TIP] > Se você não instalou o Docker na sua máquina local (Windows, Mac ou Linux), veja [Instalar Docker Engine](https://docs.docker.com/engine/install/). -### 🚀 Iniciar o servidor +#### 🚀 Iniciar o servidor 1. Certifique-se de que `vm.max_map_count` >= 262144: @@ -185,199 +197,120 @@ Experimente o nosso serviço na nuvem em [https://cloud.ragflow.io](https://clou ```bash git clone https://github.com/infiniflow/ragflow.git ``` -3. Inicie o servidor usando as imagens Docker pré-compiladas: +3. Construa a imagem Go e inicie o servidor com a configuração Compose Go. O destino oficial de build é `linux/amd64`. Consulte o [guia de build da imagem Go e suporte a plataformas](./docs/develop/build_docker_image.mdx) para obter detalhes. -> [!CAUTION] -> Todas as imagens Docker são construídas para plataformas x86. Atualmente, não oferecemos imagens Docker para ARM64. -> Se você estiver usando uma plataforma ARM64, por favor, utilize [este guia](https://ragflow.io/docs/dev/build_docker_image) para construir uma imagem Docker compatível com o seu sistema. + Antes da primeira implantação, defina `RAGFLOW_IMAGE=ragflow:go-local` em **docker/.env** e execute, a partir da raiz do repositório: - > O comando abaixo baixa a edição`v0.27.2` da imagem Docker do RAGFlow. Consulte a tabela a seguir para descrições de diferentes edições do RAGFlow. Para baixar uma edição do RAGFlow diferente da `v0.27.2`, atualize a variável `RAGFLOW_IMAGE` conforme necessário no **docker/.env** antes de usar `docker compose` para iniciar o servidor. - -```bash - cd ragflow/docker - - git checkout v0.27.2 - # Opcional: use uma tag estável (veja releases: https://github.com/infiniflow/ragflow/releases) - # Esta etapa garante que o arquivo entrypoint.sh no código corresponda à versão da imagem do Docker. - - # Use CPU for DeepDoc tasks: - docker compose -f docker-compose.yml up -d - - # To use GPU to accelerate DeepDoc tasks: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d -``` - -> Nota: Antes da `v0.22.0`, fornecíamos imagens com modelos de embedding e imagens slim sem modelos de embedding. Detalhes a seguir: - -| RAGFlow image tag | Image size (GB) | Has embedding models? | Stable? | -|-------------------|-----------------|-----------------------|----------------| -| v0.21.1 | ≈9 | ✔️ | Stable release | -| v0.21.1-slim | ≈2 | ❌ | Stable release | - -> A partir da `v0.22.0`, distribuímos apenas a edição slim e não adicionamos mais o sufixo **-slim** às tags das imagens. - -4. Verifique o status do servidor após tê-lo iniciado: - - ```bash - docker logs -f docker-ragflow-cpu-1 + ```dotenv + RAGFLOW_IMAGE=ragflow:go-local ``` - _O seguinte resultado confirma o lançamento bem-sucedido do sistema:_ - ```bash - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Rodando em todos os endereços (0.0.0.0) + cd ragflow + docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . + cd docker + docker compose --env-file .env -f docker-compose.yml up -d ``` - > Se você pular essa etapa de confirmação e acessar diretamente o RAGFlow, seu navegador pode exibir um erro `network abnormal`, pois, nesse momento, seu RAGFlow pode não estar totalmente inicializado. - > + Na configuração padrão do MySQL, o entrypoint da imagem executa as migrações do banco de dados e inicia Syncer, Admin, API e Ingestor por meio de `bin/ragflow_server`. No RAGFlow open-source 1.0, DeepDoc usa inferência por CPU para análise de layout, OCR e reconhecimento de tabelas. + +4. Verifique o estado das dependências com `docker compose --env-file .env -f docker-compose.yml ps` e confirme se o RAGFlow está pronto pela interface HTTP (o contêiner do RAGFlow não define um healthcheck do Compose): + + ```bash + curl -f http://localhost/api/v1/system/healthz + ``` + + Uma resposta HTTP 200 indica que o serviço está pronto. Se `SVR_WEB_HTTP_PORT` foi alterado, use essa porta na URL. Se a inicialização falhar, consulte os logs do serviço correspondente pelo Compose. 5. No seu navegador, insira o endereço IP do seu servidor e faça login no RAGFlow. > Com as configurações padrão, você só precisa digitar `http://IP_DO_SEU_MÁQUINA` (**sem** o número da porta), pois a porta HTTP padrão `80` pode ser omitida ao usar as configurações padrão. > -6. Em [service_conf.yaml.template](./docker/service_conf.yaml.template), selecione a fábrica LLM desejada em `user_default_llm` e atualize o campo `API_KEY` com a chave de API correspondente. - - > Consulte [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup) para mais informações. - > +6. Após entrar, adicione um LLM, um modelo de embedding e um reranker na página de provedores de modelos, incluindo o nome do modelo, o endereço do serviço e a chave de API. _O show está no ar!_ -## 🔧 Configurações +#### ⚙️ Configuração e ajustes do Docker -Quando se trata de configurações do sistema, você precisará gerenciar os seguintes arquivos: +A implantação Go com Docker usa `docker/.env` e `docker/docker-compose.yml`, com Kvrocks para cache e armazenamento de Checkpoints e NATS JetStream como fila de mensagens. Para configurar imagem, portas, senhas, mecanismo de documentos e origem das imagens de modelos, consulte o [guia de configuração do Docker](./docker/README.md). Para limitações de plataforma e requisitos do macOS, consulte o [guia de build da imagem Go e suporte a plataformas](./docs/develop/build_docker_image.mdx). -- [.env](./docker/.env): Contém as configurações fundamentais para o sistema, como `SVR_HTTP_PORT`, `MYSQL_PASSWORD` e `MINIO_PASSWORD`. -- [service_conf.yaml.template](./docker/service_conf.yaml.template): Configura os serviços de back-end. As variáveis de ambiente neste arquivo serão automaticamente preenchidas quando o contêiner Docker for iniciado. Quaisquer variáveis de ambiente definidas dentro do contêiner Docker estarão disponíveis para uso, permitindo personalizar o comportamento do serviço com base no ambiente de implantação. -- [docker-compose.yml](./docker/docker-compose.yml): O sistema depende do [docker-compose.yml](./docker/docker-compose.yml) para iniciar. +Para trocar o mecanismo de documentos, alterar configurações, reiniciar serviços e manter ou remover dados existentes, siga também o guia de configuração do Docker. -> O arquivo [./docker/README](./docker/README.md) fornece uma descrição detalhada das configurações do ambiente e dos serviços, que podem ser usadas como `${ENV_VARS}` no arquivo [service_conf.yaml.template](./docker/service_conf.yaml.template). +### 🔨 Lançar o serviço a partir do código-fonte para desenvolvimento -Para atualizar a porta HTTP de serviço padrão (80), vá até [docker-compose.yml](./docker/docker-compose.yml) e altere `80:80` para `:80`. +#### 📝 Pré-requisitos da compilação a partir do código-fonte -Atualizações nas configurações acima exigem um reinício de todos os contêineres para que tenham efeito: - -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -### Mudar o mecanismo de documentos de Elasticsearch para Infinity - -O RAGFlow usa o Elasticsearch por padrão para armazenar texto completo e vetores. Para mudar para o [Infinity](https://github.com/infiniflow/infinity/), siga estas etapas: - -1. Pare todos os contêineres em execução: - - ```bash - docker compose -f docker/docker-compose.yml down -v - ``` - - Note: `-v` irá deletar os volumes do contêiner, e os dados existentes serão apagados. -2. Defina `DOC_ENGINE` no **docker/.env** para `infinity`. -3. Inicie os contêineres: - - ```bash - docker compose -f docker/docker-compose.yml up -d - ``` - -> [!ATENÇÃO] - > A mudança para o Infinity em uma máquina Linux/arm64 ainda não é oficialmente suportada. - -## 🔧 Criar uma imagem Docker - -Esta imagem tem cerca de 2 GB de tamanho e depende de serviços externos de LLM e incorporação. - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -Se você estiver atrás de um proxy, pode passar argumentos de proxy: - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 Lançar o serviço a partir do código-fonte para desenvolvimento - -1. Instale o `uv` e o `pre-commit`, ou pule esta etapa se eles já estiverem instalados: - - ```bash - pipx install uv - ``` -2. Clone o código-fonte e instale as dependências Python: +1. Instale a versão do Go especificada em `go.mod` (atualmente Go 1.27), Clang 20, LLD 20, CMake 4.0 ou superior e os arquivos de desenvolvimento do PCRE2. Os serviços Go dependem de CGO e bibliotecas nativas; o [build.sh](./build.sh) configura os parâmetros necessários. +2. Clone o repositório, prepare as bibliotecas nativas e os arquivos de modelo necessários e compile os serviços Go: ```bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/ - uv sync --python 3.13 # instala os módulos Python dependentes do RAGFlow - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` -3. Inicie os serviços dependentes (MinIO, Elasticsearch, Redis e MySQL) usando Docker Compose: + + O script prepara as bibliotecas nativas e os recursos de modelo necessários para o build Go e requer `requests` e `huggingface-hub`. Ignore esta etapa se você já preparou os mesmos recursos de outra forma. Quando iniciados na raiz do repositório, os serviços Go encontram automaticamente `rag/res/deepdoc`; para iniciar em outro diretório, defina `DEEPDOC_MODEL_DIR` como o caminho absoluto correspondente. +3. Inicie as dependências necessárias (Elasticsearch, MySQL, MinIO, NATS, Kvrocks e ClickHouse) usando Docker Compose: ```bash - docker compose -f docker/docker-compose-base.yml up -d + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` - Adicione a seguinte linha ao arquivo `/etc/hosts` para resolver todos os hosts especificados em **docker/.env** para `127.0.0.1`: - - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. Se não conseguir acessar o HuggingFace, defina a variável de ambiente `HF_ENDPOINT` para usar um site espelho: + Os serviços Go iniciados pelo código-fonte acessam o Kvrocks exposto pelo Compose em `localhost:6379`; os serviços Docker usam o nome do host na rede dos contêineres. A configuração fornecida não exige alterações em `/etc/hosts`. +4. Execute primeiro a migração e depois inicie Admin, Ingestor, Syncer e API em quatro terminais separados, sempre na raiz do repositório. O terminal da migração pode ser fechado quando o comando terminar; os outros quatro devem permanecer abertos: ```bash - export HF_ENDPOINT=https://hf-mirror.com - ``` -5. Se o seu sistema operacional não tiver jemalloc, instale-o da seguinte maneira: + # Terminal 1: migração + ./bin/ragflow_server --migrate - ```bash - # ubuntu - sudo apt-get install libjemalloc-dev - # centos - sudo yum instalar jemalloc - # mac - brew install jemalloc - ``` -6. Lance o serviço de back-end: + # Terminal 2: Admin, porta de destino 9381 + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh + # Terminal 3: Ingestor + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + + # Terminal 4: Syncer + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + + # Terminal 5: API, porta de destino 9380 + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api ``` -7. Instale as dependências do front-end: + + Os modos de inicialização funcionam assim: + + - `--migrate`: Executa as migrações do banco de dados e encerra. + - `--admin`: Inicia o serviço Admin para operações de gerenciamento e inicialização. + - `--ingestor`: Inicia o serviço Ingestor para tarefas de ingestão e análise de dados. + - `--syncer`: Inicia o serviço Syncer para tarefas de sincronização de dados. + - `--api`: Inicia o serviço API para a interface Web, SDKs e clientes externos. + + `RAGFLOW_DEV_MODE=true` é exclusivo para desenvolvimento. Ele desativa a verificação de downgrade entre o código e as migrações, mas não executa migrações nem altera o esquema. Não o use em produção. Depois da migração, `RAGFLOW_DEV_MODE=true bash build.sh --run` pode iniciar Admin, Ingestor e API, mas não inicia o Syncer. +5. Instale Node.js e npm somente se for desenvolver o front-end: ```bash cd web npm install ``` -8. Lance o serviço de front-end: + Em seguida, inicie o serviço de front-end: ```bash - npm run dev + API_PROXY_SCHEME=go npm run dev ``` - _O seguinte resultado confirma o lançamento bem-sucedido do sistema:_ - - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) -9. Pare os serviços de front-end e back-end do RAGFlow após a conclusão do desenvolvimento: + Em outro terminal, confirme que a API Go está pronta: ```bash - pkill -f "ragflow_server.py|task_executor.py" + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` + Uma resposta HTTP 200 indica que a API está respondendo. Ao concluir o desenvolvimento, pressione `Ctrl+C` em cada terminal de serviço. Para interromper as dependências mantendo os contêineres, execute `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse`. Para remover os contêineres de dependência e a rede Compose mantendo os volumes nomeados, execute `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`. + +Consulte [Iniciar o serviço a partir do código-fonte](./docs/develop/launch_ragflow_from_source.md) para obter detalhes. + ## 📚 Documentação - [Quickstart](https://ragflow.io/docs/dev/) diff --git a/README_ru.md b/README_ru.md index d6807a6cfa..0ecc25912f 100644 --- a/README_ru.md +++ b/README_ru.md @@ -26,7 +26,7 @@ Static Badge - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Последний релиз @@ -34,9 +34,6 @@ лицензия - - Ask DeepWiki -

@@ -81,6 +78,8 @@ Попробуйте облачную версию: [https://cloud.ragflow.io](https://cloud.ragflow.io). +Для локального развёртывания см. раздел [Локальное развёртывание](#-самостоятельное-развёртывание). +
Chunking demonstration Agentic workflow demonstration @@ -88,18 +87,17 @@ ## 🔥 Последние обновления -- 2026-06-15 Поддержка нескольких каналов чата: Feishu, Discord, Telegram, Line и другие. -- 2026-04-24 Поддержка DeepSeek v4. -- 2026-03-24 [RAGFlow Skill на OpenClaw](https://clawhub.ai/yingfeng/ragflow-skill) — официальный навык для работы с датасетами RAGFlow через OpenClaw. -- 2025-12-26 Поддержка «Памяти» для AI-агентов. -- 2025-11-19 Поддержка Gemini 3 Pro. -- 2025-11-12 Синхронизация данных из Confluence, S3, Notion, Discord и Google Drive. -- 2025-10-23 Поддержка MinerU и Docling в качестве методов парсинга документов. -- 2025-10-15 Поддержка настраиваемого пайплайна ingestion. -- 2025-08-08 Поддержка новейших моделей серии GPT-5 от OpenAI. -- 2025-08-01 Поддержка агентных workflow и MCP. -- 2025-05-23 Добавлен компонент выполнения кода на Python/JavaScript в Agent. -- 2025-03-19 Поддержка мультимодальных моделей для понимания изображений внутри PDF и DOCX. +- 2026-09-10 Добавлен сбор веб-контента через sitemap. +- 2026-08-19 Представлена Knowledge Compilation для создания Wiki, Graph, Tree, PageIndex, Mind Map, Timeline и Skills на уровне документов и наборов данных. +- 2026-08-19 Представлен Agentic RAG с режимами рассуждения Low, Medium, High и Ultra. +- 2026-07-02 Добавлены источник данных Google BigQuery и инкрементальная синхронизация. +- 2026-06-29 Добавлены каналы чата WhatsApp, DingTalk и WeCom. +- 2026-05-26 Добавлен компонент Browser для просмотра и взаимодействия агентов с веб-страницами. +- 2026-04-21 Добавлены семь встроенных шаблонов конвейеров ingest данных. +- 2026-04-21 Добавлены публикация приложений Agent, выполнение кода в sandbox и генерация диаграмм. +- 2026-04-21 Добавлены хранение и поиск пользовательской памяти. + +Другие обновления см. в [полных примечаниях к выпускам](./docs/release_notes.md). ## 🎉 Следите за обновлениями @@ -113,7 +111,7 @@ ### 🍭 **«Качество на входе — качество на выходе»** -- Извлечение знаний на основе [глубокого понимания документов](./deepdoc/README.md) из неструктурированных данных со сложным форматированием. +- Извлечение знаний на основе глубокого понимания документов из неструктурированных данных со сложным форматированием. - Поиск «иголки в стоге данных» при практически неограниченном количестве токенов. ### 🍱 **Шаблонный чанкинг** @@ -121,6 +119,21 @@ - Интеллектуальный и объяснимый. - Большой выбор готовых шаблонов. +### 🧩 **Компиляция знаний (Knowledge Compilation)** + +- Преобразуйте содержимое документов и наборов данных в структурированные объекты знаний: Wiki, Graph, Tree, PageIndex, Mind Map, Timeline и Skills. +- Настраивайте модели компиляции и правила обработки, просматривайте, обновляйте и создавайте объекты знаний заново. + +### 🧠 **Агентный поиск (Agentic Retrieval)** + +- Модель анализирует сложные вопросы и при необходимости разбивает их на части, ищет знания и проверяет доказательства в несколько этапов. +- Режимы Low, Medium, High и Ultra позволяют регулировать глубину поиска и рассуждений в зависимости от сложности вопроса. + +### ⚙️ **Нативная Go-архитектура сервисов** + +- Единый сервис Go предоставляет API, Admin, Ingestor и Syncer. DeepDoc работает внутри процесса Go и выполняет анализ макета, OCR и распознавание таблиц. +- Сервисы Go вызывают нативные библиотеки обработки документов и ONNX Runtime через CGO. MCP и Sandbox Executor можно включать по мере необходимости. + ### 🌱 **Обоснованные цитаты с минимальными галлюцинациями** - Визуализация чанкинга с возможностью ручной корректировки. @@ -140,24 +153,25 @@ ## 🔎 Архитектура системы
-RAGFlow system architecture +Архитектура RAGFlow
## 🎬 Самостоятельное развёртывание -### 📝 Требования +### 🐳 Развёртывание с Docker -- CPU ≥ 4 ядра -- RAM ≥ 16 ГБ -- Диск ≥ 50 ГБ +#### 📝 Требования к развёртыванию с Docker + +- Рекомендуемая начальная конфигурация: 4 ядра CPU, 16 ГБ RAM и 50 ГБ свободного места на диске. Фактические требования зависят от движка документов, объёма данных, задач анализа и параллельной нагрузки. Для локальных моделей и других дополнительных компонентов могут потребоваться дополнительные ресурсы. - Docker ≥ 24.0.0 и Docker Compose ≥ v2.26.1 -- Python ≥ 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/) — нужен только если вы планируете использовать песочницу (code executor). +- [gVisor](https://gvisor.dev/docs/user_guide/install/) — требуется только для Self-Managed контейнерной Sandbox. + +Для Docker-развёртывания не требуется устанавливать Go на хост. Для Self-Managed контейнерной Sandbox необходимо установить и настроить gVisor; другим провайдерам Sandbox gVisor на хосте RAGFlow не требуется. > [!TIP] > Если Docker ещё не установлен (Windows, Mac или Linux), см. [Install Docker Engine](https://docs.docker.com/engine/install/). -### 🚀 Запуск сервера +#### 🚀 Запуск сервера 1. Убедитесь, что `vm.max_map_count` ≥ 262144: @@ -191,203 +205,110 @@ > Все образы собраны под x86. Образов для ARM64 пока нет. > Если вы на ARM64, следуйте [этому руководству](https://ragflow.io/docs/dev/build_docker_image), чтобы собрать образ самостоятельно. -> Команда ниже скачивает образ `v0.27.2`. Чтобы использовать другую версию, измените `RAGFLOW_IMAGE` в файле **docker/.env** перед запуском. +> Перед запуском укажите локально собранный образ в файле **docker/.env**. Официальная целевая платформа сборки Go-образа — `linux/amd64`. -```bash - cd ragflow/docker - - git checkout v0.27.2 - # Опционально: используйте стабильный тег (см. релизы) - # Это гарантирует, что entrypoint.sh соответствует версии образа. - - # CPU-режим для DeepDoc: - docker compose -f docker-compose.yml up -d - - # GPU-ускорение DeepDoc: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d +```dotenv +RAGFLOW_IMAGE=ragflow:go-local ``` -> До версии `v0.22.0` существовали образы с моделями эмбеддингов и slim-образы без них: +```bash +cd ragflow +docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . +cd docker +docker compose --env-file .env -f docker-compose.yml up -d +``` -| Тег образа RAGFlow | Размер (ГБ) | Есть модели эмбеддингов? | Стабильный? | -|--------------------|-------------|--------------------------|------------------| -| v0.21.1 | ≈9 | ✔️ | Стабильный релиз | -| v0.21.1-slim | ≈2 | ❌ | Стабильный релиз | - -> Начиная с `v0.22.0` поставляется только slim-редакция, суффикс `-slim` больше не используется. +> В открытой версии RAGFlow 1.0 DeepDoc использует CPU для анализа макета, OCR и распознавания таблиц. 4. Проверьте статус после запуска: ```bash - docker logs -f docker-ragflow-cpu-1 + docker compose --env-file .env -f docker-compose.yml ps + curl -f http://localhost/api/v1/system/healthz ``` - _Успешный запуск выглядит так:_ - - ```bash - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) - ``` - - > Если пропустить этот шаг и сразу открыть RAGFlow в браузере, может появиться ошибка `network abnormal` — система ещё не полностью инициализировалась. - 5. Откройте в браузере IP-адрес сервера и войдите в RAGFlow. > При стандартных настройках достаточно `http://IP_ВАШЕЙ_МАШИНЫ` (порт 80 можно не указывать). -6. В файле [service_conf.yaml.template](./docker/service_conf.yaml.template) выберите нужного провайдера LLM в `user_default_llm` и укажите `API_KEY`. +6. После входа добавьте LLM, модель эмбеддингов и reranker на странице поставщиков моделей, затем укажите имя модели, адрес сервиса и API-ключ. > Подробнее: [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup). _Готово!_ -## 🔧 Конфигурация +#### ⚙️ Настройка Docker -Основные файлы конфигурации: +Развёртывание Go в Docker использует `docker/.env` и `docker/docker-compose.yml`, Kvrocks для кэша и хранения Checkpoint, а NATS JetStream — в качестве очереди сообщений. Изменяйте образ, порты, пароли, движок документов и источник образов моделей в соответствии с [руководством по настройке Docker](./docker/README.md). Ограничения платформ и требования macOS описаны в [руководстве по сборке Go-образа и поддержке платформ](./docs/develop/build_docker_image.mdx). -- [.env](./docker/.env) — базовые настройки системы (`SVR_HTTP_PORT`, `MYSQL_PASSWORD`, `MINIO_PASSWORD` и др.). -- [service_conf.yaml.template](./docker/service_conf.yaml.template) — конфигурация бэкенд-сервисов. Переменные окружения подставляются автоматически при старте контейнера. -- [docker-compose.yml](./docker/docker-compose.yml) — оркестрация сервисов. +При смене движка документов, изменении конфигурации и перезапуске сервисов, а также при сохранении или удалении существующих данных следуйте этому же руководству по настройке Docker. -> Подробное описание переменных и настроек есть в [./docker/README](./docker/README.md). Их можно использовать как `${ENV_VARS}` в `service_conf.yaml.template`. +### 🔨 Запуск из исходников для разработки -Чтобы изменить HTTP-порт по умолчанию (80), в [docker-compose.yml](./docker/docker-compose.yml) замените `80:80` на `<ВАШ_ПОРТ>:80`. +#### 📝 Требования для сборки из исходников -После изменений перезапустите контейнеры: +1. Установите версию Go из `go.mod` (сейчас Go 1.27), Clang 20, LLD 20, CMake 4.0 или новее и файлы разработки PCRE2. Сервисам Go нужны CGO и нативные библиотеки; [build.sh](./build.sh) задаёт необходимые параметры сборки. -```bash -docker compose -f docker-compose.yml up -d -``` - -### Переключение с Elasticsearch на Infinity - -По умолчанию RAGFlow использует Elasticsearch. Чтобы перейти на [Infinity](https://github.com/infiniflow/infinity/): - -1. Остановите все контейнеры: - - ```bash - docker compose -f docker/docker-compose.yml down -v - ``` - -> [!WARNING] -> Флаг `-v` удалит volumes — существующие данные будут потеряны. - -2. В файле **docker/.env** установите `DOC_ENGINE=infinity`. -3. Запустите контейнеры: - - ```bash - docker compose -f docker/docker-compose.yml up -d - ``` - -> [!WARNING] -> Переключение на Infinity на Linux/arm64 пока официально не поддерживается. - -## 🔧 Сборка Docker-образа - -Образ занимает около 2 ГБ и рассчитывает на внешние LLM и сервисы эмбеддингов. - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -Если вы за прокси: - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 Запуск из исходников для разработки - -> [!IMPORTANT] -> После первого клонирования один раз выполните из корня репозитория: -> `git config --local --unset core.hooksPath`, `uv tool install lefthook` и `lefthook install`. - -1. Установите `uv` (если ещё не установлен): - - ```bash - pipx install uv - ``` - -2. Клонируйте репозиторий и установите зависимости: +2. Клонируйте репозиторий, подготовьте нативные библиотеки и файлы моделей, затем соберите сервисы Go: ```bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/ - uv sync --python 3.13 - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` -3. Запустите зависимости (MinIO, Elasticsearch, Redis, MySQL): + Скрипт подготавливает нативные библиотеки и ресурсы моделей для сборки Go и требует `requests` и `huggingface-hub`. Пропустите этот шаг, если те же ресурсы подготовлены другим способом. При запуске из корня репозитория сервисы Go автоматически находят `rag/res/deepdoc`; для запуска из другого каталога задайте `DEEPDOC_MODEL_DIR` как абсолютный путь к нему. + +3. Запустите необходимые зависимости (Elasticsearch, MySQL, MinIO, NATS, Kvrocks и ClickHouse): ```bash - docker compose -f docker/docker-compose-base.yml up -d + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` - Добавьте в `/etc/hosts`: + Сервисы Go, запущенные из исходного кода, подключаются к Kvrocks через `localhost:6379`; предоставленная конфигурация не требует изменения `/etc/hosts`. - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. Если нет доступа к HuggingFace, укажите зеркало: +4. После миграции базы данных запустите сервисы по порядку. Выполняйте каждую команду в отдельном терминале из корня репозитория и оставьте открытыми четыре терминала сервисов: ```bash - export HF_ENDPOINT=https://hf-mirror.com + ./bin/ragflow_server --migrate + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api ``` -5. Если в системе нет jemalloc: + Режимы запуска работают следующим образом: - ```bash - # Ubuntu - sudo apt-get install libjemalloc-dev - # CentOS - sudo yum install jemalloc - # OpenSUSE - sudo zypper install jemalloc - # macOS - brew install jemalloc - ``` + - `--migrate`: выполняет миграции базы данных и завершает работу. + - `--admin`: запускает сервис Admin для управления и инициализации. + - `--ingestor`: запускает сервис Ingestor для приёма и анализа данных. + - `--syncer`: запускает сервис Syncer для синхронизации данных. + - `--api`: запускает API для веб-интерфейса, SDK и внешних клиентов. -6. Запустите бэкенд: - - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh - ``` - -7. Установите зависимости фронтенда: + `RAGFLOW_DEV_MODE=true` предназначен только для разработки. Он отключает проверку отката между версиями кода и миграций базы данных, но не запускает миграции и не изменяет схему. Не используйте его в production. Запускайте Admin раньше остальных сервисов. После миграции `RAGFLOW_DEV_MODE=true bash build.sh --run` запускает Admin, Ingestor и API, но не Syncer; для полной цепочки отдельно выполните `RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer`. +5. Только для разработки фронтенда установите Node.js и npm, затем запустите React-фронтенд: ```bash cd web npm install + API_PROXY_SCHEME=go npm run dev ``` -8. Запустите фронтенд: + В другом терминале проверьте готовность Go API: ```bash - npm run dev + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` -9. После разработки остановите сервисы: + Ответ HTTP 200 означает, что API отвечает. После разработки нажмите `Ctrl+C` в каждом терминале сервиса. Чтобы остановить зависимости, сохранив контейнеры, выполните `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse`. Чтобы удалить контейнеры зависимостей и сеть Compose, сохранив именованные тома, выполните `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`. - ```bash - pkill -f "ragflow_server.py|task_executor.py" - ``` +Подробнее см. [Запуск сервиса из исходников](./docs/develop/launch_ragflow_from_source.md). ## 📚 Документация diff --git a/README_tr.md b/README_tr.md index e8f51fee86..506c349874 100644 --- a/README_tr.md +++ b/README_tr.md @@ -26,7 +26,7 @@ Çevrimiçi Demo - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Son Sürüm @@ -34,9 +34,6 @@ lisans - - Ask DeepWiki -

@@ -81,6 +78,8 @@ Bulut hizmetimizi [https://cloud.ragflow.io](https://cloud.ragflow.io) adresinden deneyin. +Yerel dağıtım için [Kendi Sunucusunda Barındırma](#-kendi-sunucusunda-barındırma) bölümüne bakın. +
Chunking demonstration Agentic workflow demonstration @@ -88,18 +87,17 @@ Bulut hizmetimizi [https://cloud.ragflow.io](https://cloud.ragflow.io) adresinde ## 🔥 Son Güncellemeler -- 2026-06-15 Feishu, Discord, Telegram, Line vb. gibi birden fazla sohbet kanalını destekleyin. -- 2026-04-24 DeepSeek v4 desteği. -- 2026-03-24 [RAGFlow Skill on OpenClaw](https://clawhub.ai/yingfeng/ragflow-skill) — OpenClaw üzerinden RAGFlow veri setlerine erişmek için resmi bir skill sağlar. -- 2025-12-26 Yapay zeka ajanı için 'Bellek' desteği eklendi. -- 2025-11-19 Gemini 3 Pro desteği eklendi. -- 2025-11-12 Confluence, S3, Notion, Discord, Google Drive'dan veri senkronizasyonu desteği eklendi. -- 2025-10-23 Doküman ayrıştırma yöntemi olarak MinerU ve Docling desteği eklendi. -- 2025-10-15 Düzenlenebilir veri alım hattı desteği eklendi. -- 2025-08-08 OpenAI'ın en yeni GPT-5 serisi modelleri için destek eklendi. -- 2025-08-01 Ajanlı iş akışı ve MCP desteği eklendi. -- 2025-05-23 Ajana Python/JavaScript kod çalıştırıcı bileşeni eklendi. -- 2025-03-19 PDF veya DOCX dosyalarındaki görselleri yorumlamak için çok modlu model desteği eklendi. +- 2026-09-10 Site haritaları üzerinden web içeriği alımı eklendi. +- 2026-08-19 Belge ve veri kümesi düzeyinde Wiki, Graph, Tree, PageIndex, Mind Map, Timeline ve Skills üretmek için Knowledge Compilation tanıtıldı. +- 2026-08-19 Low, Medium, High ve Ultra düşünme modlarına sahip Agentic RAG tanıtıldı. +- 2026-07-02 Google BigQuery veri kaynağı alımı ve artımlı eşitleme eklendi. +- 2026-06-29 WhatsApp, DingTalk ve WeCom sohbet kanalları eklendi. +- 2026-05-26 Agent'ların web sayfalarında gezinip işlem yapmasını sağlayan Browser bileşeni eklendi. +- 2026-04-21 Yedi yerleşik veri alım hattı şablonu eklendi. +- 2026-04-21 Agent uygulamalarını yayımlama, sandbox kod yürütme ve grafik oluşturma eklendi. +- 2026-04-21 Kullanıcı düzeyinde bellek depolama ve erişimi eklendi. + +Diğer güncellemeler için [tam sürüm notlarına](./docs/release_notes.md) bakın. ## 🎉 Bizi Takip Edin @@ -113,7 +111,7 @@ Bulut hizmetimizi [https://cloud.ragflow.io](https://cloud.ragflow.io) adresinde ### 🍭 **"Kaliteli girdi, kaliteli çıktı"** -- Karmaşık formatlara sahip yapılandırılmamış verilerden [derin doküman anlayışı](./deepdoc/README.md) tabanlı bilgi çıkarımı. +- Karmaşık formatlara sahip yapılandırılmamış verilerden derin doküman anlayışı tabanlı bilgi çıkarımı. - Kelimenin tam anlamıyla sınırsız token içinde "samanlıkta iğne bulma" yeteneği. ### 🍱 **Şablon tabanlı parçalama** @@ -121,6 +119,21 @@ Bulut hizmetimizi [https://cloud.ragflow.io](https://cloud.ragflow.io) adresinde - Akıllı ve açıklanabilir. - Aralarından seçim yapabileceğiniz çok sayıda şablon seçeneği. +### 🧩 **Bilgi Derleme (Knowledge Compilation)** + +- Belge ve veri kümesi içeriğini Wiki, Graph, Tree, PageIndex, Mind Map, Timeline ve Skills gibi yapılandırılmış bilgi çıktılarına dönüştürün. +- Derleme modellerini ve işleme kurallarını yapılandırın; bilgi çıktılarını görüntüleyin, güncelleyin veya yeniden oluşturun. + +### 🧠 **Agentic Retrieval** + +- Karmaşık soruları analiz edin; gerektiğinde soruları alt parçalara ayırın, bilgi arayın ve kanıtları birden fazla adımda doğrulayın. +- Low, Medium, High ve Ultra düşünme modlarıyla arama ve akıl yürütme derinliğini sorunun karmaşıklığına göre ayarlayın. + +### ⚙️ **Go yerel servis mimarisi** + +- API, Admin, Ingestor ve Syncer birleşik bir Go servisi tarafından sunulur. DeepDoc, Go süreci içinde sayfa düzeni analizi, OCR ve tablo tanımayı yürütür. +- Go servisleri CGO üzerinden yerel belge ayrıştırma kitaplıklarını ve ONNX Runtime'ı çağırır. MCP ve Sandbox Executor gerektiğinde etkinleştirilebilir. + ### 🌱 **Azaltılmış halüsinasyonlarla temellendirilmiş alıntılar** - İnsan müdahalesine olanak tanıyan metin parçalama görselleştirmesi. @@ -140,24 +153,25 @@ Bulut hizmetimizi [https://cloud.ragflow.io](https://cloud.ragflow.io) adresinde ## 🔎 Sistem Mimarisi
-RAGFlow system architecture +RAGFlow sistem mimarisi
## 🎬 Kendi Sunucusunda Barındırma -### 📝 Ön Koşullar +### 🐳 Docker Dağıtımı -- CPU >= 4 çekirdek -- RAM >= 16 GB -- Disk >= 50 GB +#### 📝 Docker Dağıtımı Ön Koşulları + +- Önerilen başlangıç yapılandırması: 4 CPU çekirdeği, 16 GB RAM ve 50 GB kullanılabilir disk alanı. Gerçek gereksinimler belge motoruna, veri hacmine, ayrıştırma görevlerine ve eşzamanlılığa bağlıdır. Yerel modeller ve diğer isteğe bağlı bileşenler ek kaynak gerektirebilir. - Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- Python >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/): Yalnızca RAGFlow'un kod çalıştırıcı (sandbox) özelliğini kullanmayı planlıyorsanız gereklidir. +- [gVisor](https://gvisor.dev/docs/user_guide/install/): Yalnızca Self-Managed kapsayıcı Sandbox kullanılırken gereklidir. + +Docker dağıtımı ana makineye Go kurulmasını gerektirmez. Self-Managed kapsayıcı Sandbox, gVisor kurulumu ve yapılandırması gerektirir; diğer Sandbox sağlayıcıları RAGFlow ana makinesinde gVisor gerektirmez. > [!TIP] > Yerel makinenize (Windows, Mac veya Linux) Docker yüklemediyseniz, [Docker Engine Kurulumu](https://docs.docker.com/engine/install/) sayfasına bakın. -### 🚀 Sunucuyu Başlatma +#### 🚀 Sunucuyu Başlatma 1. `vm.max_map_count` değerinin >= 262144 olduğundan emin olun: @@ -192,200 +206,109 @@ Bulut hizmetimizi [https://cloud.ragflow.io](https://cloud.ragflow.io) adresinde > Tüm Docker imajları x86 platformları için oluşturulmuştur. Şu anda ARM64 için Docker imajı sunmuyoruz. > ARM64 platformundaysanız, sisteminizle uyumlu bir Docker imajı oluşturmak için [bu kılavuzu](https://ragflow.io/docs/dev/build_docker_image) takip edin. -> Aşağıdaki komut RAGFlow Docker imajının `v0.27.2` sürümünü indirir. Farklı RAGFlow sürümleri için aşağıdaki tabloya bakın. `v0.27.2` dışında bir sürüm indirmek için, `docker compose` ile sunucuyu başlatmadan önce **docker/.env** dosyasındaki `RAGFLOW_IMAGE` değişkenini güncelleyin. +> Başlatmadan önce yerel olarak oluşturulan imajı **docker/.env** dosyasında seçin. Go imajının resmi derleme hedefi `linux/amd64` platformudur. -```bash - cd ragflow/docker - - git checkout v0.27.2 - # İsteğe bağlı: Kararlı bir etiket kullanın (sürümler: https://github.com/infiniflow/ragflow/releases) - # Bu adım, koddaki **entrypoint.sh** dosyasının Docker imaj sürümüyle eşleşmesini sağlar. - - # DeepDoc görevleri için CPU kullanımı: - docker compose -f docker-compose.yml up -d - - # DeepDoc görevlerini hızlandırmak için GPU kullanımı: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d +```dotenv +RAGFLOW_IMAGE=ragflow:go-local ``` -> Not: `v0.22.0` öncesinde hem gömme modelleri içeren imajlar hem de gömme modelleri içermeyen ince (slim) imajlar sunuyorduk. Detaylar aşağıdadır: +```bash +cd ragflow +docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . +cd docker +docker compose --env-file .env -f docker-compose.yml up -d +``` -| RAGFlow imaj etiketi | İmaj boyutu (GB) | Gömme modelleri var mı? | Kararlı mı? | -|-----------------------|-------------------|-------------------------|-----------------| -| v0.21.1 | ≈9 | ✔️ | Kararlı sürüm | -| v0.21.1-slim | ≈2 | ❌ | Kararlı sürüm | - -> `v0.22.0`'dan itibaren yalnızca ince (slim) sürümü sunuyoruz ve imaj etiketine artık **-slim** son eki eklemiyoruz. +> RAGFlow açık kaynak 1.0 sürümünde DeepDoc, düzen analizi, OCR ve tablo tanıma için CPU çıkarımı kullanır. 4. Sunucu çalışır duruma geldikten sonra sunucu durumunu kontrol edin: ```bash - docker logs -f docker-ragflow-cpu-1 + docker compose --env-file .env -f docker-compose.yml ps + curl -f http://localhost/api/v1/system/healthz ``` - _Aşağıdaki çıktı, sistemin başarıyla başlatıldığını onaylar:_ - - ```bash - - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) - ``` - - > Bu onay adımını atlayıp doğrudan RAGFlow'a giriş yaparsanız, o anda RAGFlow tam olarak başlatılmamış olabileceğinden - > tarayıcınız `ağ hatası` uyarısı verebilir. - > 5. Web tarayıcınıza sunucunuzun IP adresini girin ve RAGFlow'a giriş yapın. > Varsayılan ayarlarla, yalnızca `http://MAKİNENİZİN_IP_ADRESİ` girmeniz yeterlidir (port numarası **gerekmez**), > çünkü varsayılan HTTP sunucu portu `80` varsayılan yapılandırmalar kullanıldığında ihmal edilebilir. > -6. [service_conf.yaml.template](./docker/service_conf.yaml.template) dosyasında, `user_default_llm` içinde istediğiniz LLM sağlayıcısını seçin ve - `API_KEY` alanını ilgili API anahtarıyla güncelleyin. +6. RAGFlow'a giriş yaptıktan sonra model sağlayıcıları sayfasından LLM, embedding modeli ve reranker ekleyin; model adını, servis adresini ve API anahtarını girin. > Daha fazla bilgi için [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup) sayfasına bakın. > _Gösteri başlasın!_ -## 🔧 Yapılandırmalar +#### ⚙️ Docker Yapılandırması ve Ayarlama -Sistem yapılandırmaları söz konusu olduğunda, aşağıdaki dosyaları yönetmeniz gerekecektir: +Go Docker dağıtımı `docker/.env` ve `docker/docker-compose.yml` dosyalarını kullanır; önbellek ve Checkpoint depolaması için Kvrocks, mesaj kuyruğu olarak da NATS JetStream kullanılır. İmajı, bağlantı noktalarını, parolaları, belge motorunu ve model imajı kaynağını değiştirmek için [Docker yapılandırma kılavuzunu](./docker/README.md) izleyin. Platform sınırlamaları ve macOS gereksinimleri için [Go Docker imajı oluşturma ve platform desteği kılavuzuna](./docs/develop/build_docker_image.mdx) bakın. -- [.env](./docker/.env): `SVR_HTTP_PORT`, `MYSQL_PASSWORD` ve `MINIO_PASSWORD` gibi temel sistem ayarlarını içerir. -- [service_conf.yaml.template](./docker/service_conf.yaml.template): Arka uç hizmetlerini yapılandırır. Bu dosyadaki ortam değişkenleri, Docker konteyneri başladığında otomatik olarak doldurulacaktır. Docker konteyneri içinde ayarlanan tüm ortam değişkenleri kullanıma hazır olacak ve hizmet davranışını dağıtım ortamına göre özelleştirmenize olanak tanıyacaktır. -- [docker-compose.yml](./docker/docker-compose.yml): Sistem, başlatılmak için [docker-compose.yml](./docker/docker-compose.yml) dosyasına dayanır. +Belge motorunu değiştirme, yapılandırma değişikliklerinden sonra hizmetleri yeniden başlatma ve mevcut verileri koruma veya temizleme işlemleri için de yukarıdaki Docker yapılandırma kılavuzunu izleyin. -> [./docker/README](./docker/README.md) dosyası, [service_conf.yaml.template](./docker/service_conf.yaml.template) dosyasında `${ENV_VARS}` olarak kullanılabilen ortam ayarları ve hizmet yapılandırmalarının ayrıntılı bir açıklamasını sağlar. +### 🔨 Geliştirme İçin Kaynaktan Hizmet Başlatma -Varsayılan HTTP sunucu portunu (80) değiştirmek için [docker-compose.yml](./docker/docker-compose.yml) dosyasında `80:80` ifadesini `:80` olarak değiştirin. +#### 📝 Kaynaktan Derleme Ön Koşulları -Yukarıdaki yapılandırma değişikliklerinin etkili olması için tüm konteynerlerin yeniden başlatılması gerekir: - -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -### Doküman Motorunu Elasticsearch'ten Infinity'ye Geçirme - -RAGFlow varsayılan olarak tam metin ve vektörlerin depolanması için Elasticsearch kullanır. [Infinity](https://github.com/infiniflow/infinity/)'ye geçmek için şu adımları izleyin: - -1. Çalışan tüm konteynerleri durdurun: - - ```bash - docker compose -f docker/docker-compose.yml down -v - ``` - -> [!WARNING] -> `-v` seçeneği Docker konteyner birimlerini silecek ve mevcut veriler temizlenecektir. - -2. **docker/.env** dosyasında `DOC_ENGINE` değerini `infinity` olarak ayarlayın. -3. Konteynerleri başlatın: - - ```bash - docker compose -f docker/docker-compose.yml up -d - ``` - -> [!WARNING] -> Linux/arm64 makinesinde Infinity'ye geçiş henüz resmi olarak desteklenmemektedir. - -## 🔧 Docker İmajı Oluşturma - -Bu imaj yaklaşık 2 GB boyutundadır ve harici LLM ile gömme hizmetlerine bağlıdır. - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -Veya bir proxy arkasındaysanız, proxy parametrelerini iletebilirsiniz: - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://PROXY_ADRESINIZ:PORT \ - --build-arg https_proxy=http://PROXY_ADRESINIZ:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 Geliştirme İçin Kaynaktan Hizmet Başlatma - -1. `uv` yükleyin veya zaten yüklüyse bu adımı atlayın: - - ```bash - pipx install uv - ``` -2. Kaynak kodunu klonlayın ve Python bağımlılıklarını yükleyin: +1. `go.mod` dosyasında belirtilen Go sürümünü (şu anda Go 1.27), Clang 20, LLD 20, CMake 4.0 veya üzerini ve PCRE2 geliştirme dosyalarını yükleyin. Go hizmetleri CGO ve yerel kitaplıklara bağlıdır; [build.sh](./build.sh) gerekli derleme parametrelerini ayarlar. +2. Depoyu klonlayın, gerekli yerel kitaplıkları ve model dosyalarını hazırlayın, ardından Go hizmetlerini derleyin: ```bash git clone https://github.com/infiniflow/ragflow.git cd ragflow/ - uv sync --python 3.13 # RAGFlow'un bağımlı Python modüllerini yükler - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` -3. Bağımlı hizmetleri (MinIO, Elasticsearch, Redis ve MySQL) Docker Compose kullanarak başlatın: + + Betik, Go derlemesi için gerekli yerel kitaplıkları ve model kaynaklarını hazırlar ve `requests` ile `huggingface-hub` gerektirir. Aynı kaynakları başka bir yöntemle hazırladıysanız bu adımı atlayabilirsiniz. Depo kökünden başlatıldığında Go hizmetleri `rag/res/deepdoc` dizinini otomatik olarak bulur; başka bir dizinden başlatmak için `DEEPDOC_MODEL_DIR` değişkenini mutlak yola ayarlayın. +3. Gerekli bağımlılıkları (Elasticsearch, MySQL, MinIO, NATS, Kvrocks ve ClickHouse) Docker Compose ile başlatın: ```bash - docker compose -f docker/docker-compose-base.yml up -d + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` - **docker/.env** dosyasında belirtilen tüm ana bilgisayar adlarını `127.0.0.1`'e çözümlemek için `/etc/hosts` dosyasına aşağıdaki satırı ekleyin: + Kaynaktan çalıştırılan Go hizmetleri Kvrocks'a `localhost:6379` üzerinden bağlanır; sağlanan yapılandırmada `/etc/hosts` değişikliği gerekmez. - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. HuggingFace'e erişemiyorsanız, bir ayna site kullanmak için `HF_ENDPOINT` ortam değişkenini ayarlayın: +4. Veritabanı geçişinden sonra hizmetleri belirtilen sırayla başlatın. Her komutu deponun kök dizininden ayrı bir terminalde çalıştırın ve dört hizmet terminalini açık bırakın: ```bash - export HF_ENDPOINT=https://hf-mirror.com + ./bin/ragflow_server --migrate + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api ``` -5. İşletim sisteminizde jemalloc yoksa, aşağıdaki şekilde yükleyin: - ```bash - # Ubuntu - sudo apt-get install libjemalloc-dev - # CentOS - sudo yum install jemalloc - # OpenSUSE - sudo zypper install jemalloc - # macOS - brew install jemalloc - ``` -6. Arka uç hizmetini başlatın: + Başlatma modları şu şekilde çalışır: - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh - ``` -7. Ön yüz bağımlılıklarını yükleyin: + - `--migrate`: Veritabanı geçişlerini çalıştırır ve tamamlanınca çıkar. + - `--admin`: Yönetim ve başlatma işlemleri için Admin hizmetini başlatır. + - `--ingestor`: Veri alımı ve ayrıştırma görevleri için Ingestor hizmetini başlatır. + - `--syncer`: Veri eşitleme görevleri için Syncer hizmetini başlatır. + - `--api`: Web UI, SDK'lar ve harici istemciler için API hizmetini başlatır. + + `RAGFLOW_DEV_MODE=true` yalnızca geliştirme içindir. Kod sürümü ile veritabanı geçiş sürümü arasındaki sürüm düşürme denetimini devre dışı bırakır ancak geçiş çalıştırmaz veya şemayı değiştirmez. Üretimde kullanmayın. Admin'i diğer hizmetlerden önce başlatın. Geçişten sonra `RAGFLOW_DEV_MODE=true bash build.sh --run` Admin, Ingestor ve API'yi başlatır ancak Syncer'ı başlatmaz; tam hizmet zinciri için `RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer` komutunu ayrıca çalıştırın. +5. Yalnızca ön yüz geliştirirken Node.js ve npm'i yükleyin, ardından React ön yüzünü başlatın: ```bash cd web npm install + API_PROXY_SCHEME=go npm run dev ``` -8. Ön yüz hizmetini başlatın: + + Başka bir terminalde Go API'nin hazır olduğunu doğrulayın: ```bash - npm run dev + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` - _Aşağıdaki çıktı, sistemin başarıyla başlatıldığını onaylar:_ + HTTP 200 yanıtı API'nin yanıt verdiğini gösterir. Geliştirme tamamlandığında her hizmet terminalinde `Ctrl+C` tuşlarına basın. Kapsayıcıları koruyarak bağımlılıkları durdurmak için `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse` komutunu çalıştırın. Adlandırılmış birimleri koruyarak bağımlılık kapsayıcılarını ve Compose ağını kaldırmak için `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down` komutunu çalıştırın. - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) -9. Geliştirme tamamlandıktan sonra RAGFlow ön yüz ve arka uç hizmetini durdurun: - - ```bash - pkill -f "ragflow_server.py|task_executor.py" - ``` +Ayrıntılar için [Hizmeti Kaynaktan Başlatma](./docs/develop/launch_ragflow_from_source.md) belgesine bakın. ## 📚 Dokümantasyon diff --git a/README_tzh.md b/README_tzh.md index 799c449b0a..b095cb75a4 100644 --- a/README_tzh.md +++ b/README_tzh.md @@ -26,7 +26,7 @@ Static Badge - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Latest Release @@ -34,9 +34,6 @@ license - - Ask DeepWiki -

@@ -81,6 +78,8 @@ 請登入網址 [https://cloud.ragflow.io](https://cloud.ragflow.io) 試用雲服務。 +如需本機部署，請參閱[本機部署](#-自行架設)。 +
Chunking demonstration Agentic workflow demonstration @@ -88,18 +87,17 @@ ## 🔥 近期更新 -- 2026-06-15 支援飛書、Discord、Telegram、Line 等多種聊天管道。 -- 2026-04-24 支援 DeepSeek v4 版本。 -- 2026-03-24 發布 [RAGFlow 官方 Skill](https://clawhub.ai/yingfeng/ragflow-skill) — 提供官方 Skill 以透過 OpenClaw 訪問 RAGFlow 數據集。 -- 2025-12-26 支援AI代理的「記憶」功能。 -- 2025-11-19 支援 Gemini 3 Pro。 -- 2025-11-12 支援從 Confluence、S3、Notion、Discord、Google Drive 進行資料同步。 -- 2025-10-23 支援 MinerU 和 Docling 作為文件解析方法。 -- 2025-10-15 支援可編排的資料管道。 -- 2025-08-08 支援 OpenAI 最新的 GPT-5 系列模型。 -- 2025-08-01 支援 agentic workflow 和 MCP。 -- 2025-05-23 為 Agent 新增 Python/JS 程式碼執行器元件。 -- 2025-03-19 PDF和DOCX中的圖支持用多模態大模型去解析得到描述。 +- 2026-09-10 支援透過 Sitemap 接入網站內容。 +- 2026-08-19 推出知識編譯，支援在文件級和知識庫級產生 Wiki、Graph、Tree、PageIndex、Mind Map、Timeline 及 Skills。 +- 2026-08-19 推出 Agentic RAG，支援 Low、Medium、High、Ultra 四種思考模式。 +- 2026-07-02 支援 Google BigQuery 資料來源接入與增量同步。 +- 2026-06-29 支援 WhatsApp、釘釘和企業微信聊天管道。 +- 2026-05-26 新增 Browser 元件，支援 Agent 自主瀏覽和操作網頁。 +- 2026-04-21 提供七種預置資料攝取流水線範本。 +- 2026-04-21 支援 Agent 應用程式發布、Sandbox 程式碼執行與圖表產生。 +- 2026-04-21 支援使用者級記憶儲存和檢索。 + +更多更新請參閱[完整發布記錄](./docs/release_notes.md)。 ## 🎉 關注項目 @@ -114,7 +112,7 @@ ### 🍭 **"Quality in, quality out"** -- 基於[深度文件理解](./deepdoc/README.md)，能夠從各類複雜格式的非結構化資料中提取真知灼見。 +- 基於深度文件理解，能夠從各類複雜格式的非結構化資料中提取真知灼見。 - 真正在無限上下文（token）的場景下快速完成大海撈針測試。 ### 🍱 **基於模板的文字切片** @@ -122,6 +120,25 @@ - 不只是智能，更重要的是可控可解釋。 - 多種文字範本可供選擇 +### 🧩 **知識編譯（Knowledge Compilation）** + +- 支援文件級和知識庫級編譯，將原始內容整理為結構化知識產物。 +- 透過編譯範本產生 Wiki、Graph、Tree、PageIndex、Mind Map、Timeline 及 Skills，滿足不同的知識組織與重用需求。 +- 支援設定編譯模型與處理規則，並檢視、更新和重新產生知識產物。 + +### 🧠 **Agentic Retrieval** + +- 針對複雜問題進行多步檢索：模型會分析問題，並在需要時執行問題拆解、知識檢索和證據核驗。 +- 透過多輪檢索與推理取得更完整的上下文，協助產生有依據的回答。 +- 支援 Low、Medium、High、Ultra 思考模式，可依問題複雜度控制檢索和推理深度。 + +### ⚙️ **Go 原生服務架構** + +- API、Admin、Ingestor 和 Syncer 由 Go 服務統一提供。 +- DeepDoc 在 Go 行程內執行，負責版面分析、OCR 和表格辨識。 +- Go 服務透過 CGO 呼叫原生文件解析程式庫和 ONNX Runtime。 +- MCP 和 Sandbox Executor 是可按需啟用的選用能力。 + ### 🌱 **有理有據、最大程度降低幻覺（hallucination）** - 文字切片過程視覺化，支援手動調整。 @@ -141,26 +158,27 @@ ## 🔎 系統架構
-RAGFlow system architecture +RAGFlow 系統架構
## 🎬 自行架設 -### 📝 前提條件 +### 🐳 Docker 部署 -- CPU >= 4 核 -- RAM >= 16 GB -- Disk >= 50 GB +#### 📝 Docker 部署前提條件 + +- 建議起步配置：4 核 CPU、16 GB 記憶體和 50 GB 可用磁碟。實際資源需求取決於文件引擎、資料規模、解析任務和並發量；啟用本機模型或其他額外元件時，請同時滿足相應元件的資源需求。 - Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- Python >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/): 僅在您打算使用 RAGFlow 的代碼執行器（沙箱）功能時才需要安裝。 +- [gVisor](https://gvisor.dev/docs/user_guide/install/): 僅在使用 Self-Managed 容器 Sandbox 時需要安裝和設定。 + +Docker 部署無需在主機安裝 Go。使用 Self-Managed 容器 Sandbox 時需要額外安裝和設定 gVisor，其他 Sandbox Provider 不要求在 RAGFlow 主機安裝 gVisor。 > [!TIP] > 如果你並沒有在本機安裝 Docker（Windows、Mac，或 Linux）, 可以參考文件 [Install Docker Engine](https://docs.docker.com/engine/install/) 自行安裝。 -### 🚀 啟動伺服器 +#### 🚀 啟動伺服器 -1. 確保 `vm.max_map_count` 不小於 262144： +1. 如果使用 Elasticsearch，請將 Docker 主機的 `vm.max_map_count` 設為至少 262144。使用 Infinity 時通常不需要執行此步驟： > 如需確認 `vm.max_map_count` 的大小： > @@ -186,210 +204,133 @@ ```bash git clone https://github.com/infiniflow/ragflow.git ``` -3. 進入 **docker** 資料夾，利用事先編譯好的 Docker 映像啟動伺服器： +3. 建置 Go 版映像，並使用 Go 版 Compose 設定啟動伺服器： -> [!CAUTION] -> 所有 Docker 映像檔都是為 x86 平台建置的。目前，我們不提供 ARM64 平台的 Docker 映像檔。 -> 如果您使用的是 ARM64 平台，請使用 [這份指南](https://ragflow.io/docs/dev/build_docker_image) 來建置適合您系統的 Docker 映像檔。 +> [!NOTE] +> Go 映像的正式建置目標為 `linux/amd64`。平台限制和 macOS 要求請參閱[Go Docker 映像建置與平台支援指南](./docs/develop/build_docker_image.mdx)。 -> 執行以下指令會自動下載 RAGFlow Docker 映像 `v0.27.2`。請參考下表查看不同 Docker 發行版的說明。如需下載不同於 `v0.27.2` 的 Docker 映像，請在執行 `docker compose` 啟動服務之前先更新 **docker/.env** 檔案內的 `RAGFLOW_IMAGE` 變數。 +> 首次部署前需要先建置 Go 映像，建置時間取決於網路和機器效能。 -```bash - cd ragflow/docker +將以下值寫入 `docker/.env`： - git checkout v0.27.2 - # 可選：使用穩定版標籤（查看發佈：https://github.com/infiniflow/ragflow/releases） - # 此步驟確保程式碼中的 entrypoint.sh 檔案與 Docker 映像版本一致。 - - # Use CPU for DeepDoc tasks: - docker compose -f docker-compose.yml up -d - - # To use GPU to accelerate DeepDoc tasks: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d +```dotenv +RAGFLOW_IMAGE=ragflow:go-local ``` -> 注意：在 `v0.22.0` 之前的版本，我們會同時提供包含 embedding 模型的映像和不含 embedding 模型的 slim 映像。具體如下： +```bash + cd ragflow + docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . + cd docker + docker compose --env-file .env -f docker-compose.yml up -d +``` -| RAGFlow image tag | Image size (GB) | Has embedding models? | Stable? | -|-------------------|-----------------|-----------------------|----------------| -| v0.21.1 | ≈9 | ✔️ | Stable release | -| v0.21.1-slim | ≈2 | ❌ | Stable release | +預設 MySQL 設定下，Go 映像入口會先執行資料庫遷移，再透過 `bin/ragflow_server` 啟動 Syncer、Admin、API 和 Ingestor。 -> 從 `v0.22.0` 開始，我們只發佈 slim 版本，並且不再在映像標籤後附加 **-slim** 後綴。 +> RAGFlow 開源版 1.0 的 DeepDoc 版面分析、OCR 和表格辨識使用 CPU 推理。 -> [!TIP] -> 如果你遇到 Docker 映像檔拉不下來的問題，可以在 **docker/.env** 檔案內根據變數 `RAGFLOW_IMAGE` 的註解提示選擇華為雲或阿里雲的對應映像。 -> -> - 華為雲鏡像名：`swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow` -> - 阿里雲鏡像名：`registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow` - -4. 伺服器啟動成功後再次確認伺服器狀態： +4. 檢查相依服務狀態及 API 是否就緒： ```bash - docker logs -f docker-ragflow-cpu-1 + docker compose --env-file .env -f docker-compose.yml ps ``` - _出現以下介面提示說明伺服器啟動成功：_ + 相依服務顯示健康且 RAGFlow 容器持續執行後，請透過 HTTP 介面確認 RAGFlow 是否就緒（RAGFlow 容器本身未定義 Compose healthcheck）： ```bash - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) + curl -f http://localhost/api/v1/system/healthz ``` - > 如果您跳過這一步驟系統確認步驟就登入 RAGFlow，你的瀏覽器有可能會提示 `network abnormal` 或 `網路異常`，因為 RAGFlow 可能並未完全啟動成功。 - > + 返回 HTTP 200 表示 RAGFlow 已就緒。若修改了 `SVR_WEB_HTTP_PORT`，請將健康檢查網址中的連接埠替換為對應值。啟動異常時，請使用 Compose 查看對應服務日誌。 5. 在你的瀏覽器中輸入你的伺服器對應的 IP 位址並登入 RAGFlow。 > 上面這個範例中，您只需輸入 http://IP_OF_YOUR_MACHINE 即可：未改動過設定則無需輸入連接埠（預設的 HTTP 服務連接埠 80）。 > -6. 在 [service_conf.yaml.template](./docker/service_conf.yaml.template) 檔案的 `user_default_llm` 欄位設定 LLM factory，並在 `API_KEY` 欄填入和你選擇的大模型相對應的 API key。 - - > 詳見 [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup)。 - > +6. 登入 RAGFlow 後，在模型提供商頁面新增 LLM、Embedding 和 Reranker，並填寫對應的模型名稱、服務位址和 API key。 _好戲開始，接著奏樂接著舞！ _ -## 🔧 系統配置 +#### ⚙️ Docker 設定與調整 -系統配置涉及以下三份文件： +Go 版 Docker 部署使用 `docker/.env` 和 `docker/docker-compose.yml`，以 Kvrocks 儲存快取和 Checkpoint，並使用 NATS JetStream 作為訊息佇列。映像、連接埠、密碼、文件引擎和模型映像來源，請參閱 [Docker 設定說明](./docker/README.md)。平台限制和 macOS 執行要求，請參閱 [Go Docker 映像建置與平台支援指南](./docs/develop/build_docker_image.mdx)。 -- [.env](./docker/.env)：存放一些系統環境變量，例如 `SVR_HTTP_PORT`、`MYSQL_PASSWORD`、`MINIO_PASSWORD` 等。 -- [service_conf.yaml.template](./docker/service_conf.yaml.template)：設定各類別後台服務。 -- [docker-compose.yml](./docker/docker-compose.yml): 系統依賴該檔案完成啟動。 +切換文件引擎、更新設定、重新啟動服務，以及保留或清除既有資料等操作，也請依照上述 Docker 設定文件執行。 -請務必確保 [.env](./docker/.env) 檔案中的變數設定與 [service_conf.yaml.template](./docker/service_conf.yaml.template) 檔案中的設定保持一致！ +### 🔨 以原始碼啟動 Go 服務 -如果無法存取映像網站 hub.docker.com 或模型網站 huggingface.co，請依照 [.env](./docker/.env) 註解修改 `RAGFLOW_IMAGE` 和 `HF_ENDPOINT`。 +#### 📝 原始碼啟動前提條件 -> [./docker/README](./docker/README.md) 解釋了 [service_conf.yaml.template](./docker/service_conf.yaml.template) 用到的環境變數設定和服務配置。 +原始碼啟動需要安裝 `go.mod` 指定的 Go 版本（目前為 Go 1.27）、Clang 20、LLD 20、CMake >= 4.0、PCRE2 開發檔案，以及 CGO 所需的原生程式庫。僅開發 React 前端時需要 Node.js 和 npm。 -如需更新預設的 HTTP 服務連接埠(80), 可以在[docker-compose.yml](./docker/docker-compose.yml) 檔案中將配置 `80:80` 改為 `:80` 。 - -> 所有系統配置都需要透過系統重新啟動生效： -> -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -###把文檔引擎從 Elasticsearch 切換成為 Infinity - -RAGFlow 預設使用 Elasticsearch 儲存文字和向量資料. 如果要切換為 [Infinity](https://github.com/infiniflow/infinity/), 可以按照下面步驟進行: - -1. 停止所有容器運作: - - ```bash - docker compose -f docker/docker-compose.yml down -v - ``` - - Note: `-v` 將會刪除 docker 容器的 volumes，已有的資料會被清空。 -2. 設定 **docker/.env** 目錄中的 `DOC_ENGINE` 為 `infinity`. -3. 啟動容器: - - ```bash - docker compose -f docker/docker-compose.yml up -d - ``` - -> [!WARNING] -> Infinity 目前官方並未正式支援在 Linux/arm64 架構下的機器上運行. - -## 🔧 原始碼編譯 Docker 映像 - -本 Docker 映像大小約 2 GB 左右並且依賴外部的大模型和 embedding 服務。 - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -若您位於代理環境，可傳遞代理參數： - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 以原始碼啟動服務 - -1. 安裝 `uv`。如已安裝，可跳過此步驟： - - ```bash - pipx install uv - export UV_INDEX=https://mirrors.aliyun.com/pypi/simple - ``` -2. 下載原始碼並安裝 Python 依賴： +1. 複製倉庫，並安裝上述建置工具： ```bash git clone https://github.com/infiniflow/ragflow.git - cd ragflow/ - uv sync --python 3.13 # install RAGFlow dependent python modules - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + cd ragflow ``` -3. 透過 Docker Compose 啟動依賴的服務（MinIO, Elasticsearch, Redis, and MySQL）： +2. 使用 [Go 依賴下載腳本](./ragflow_deps/download_go_deps.py)準備原生程式庫和模型檔案，再編譯 Go 服務： ```bash - docker compose -f docker/docker-compose-base.yml up -d + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` - 在 `/etc/hosts` 中加入以下程式碼，將 **conf/service_conf.yaml** 檔案中的所有 host 位址都解析為 `127.0.0.1`： - - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. 如果無法存取 HuggingFace，可以把環境變數 `HF_ENDPOINT` 設為對應的鏡像網站： + 下載腳本使用 `requests` 和 `huggingface-hub` 來準備 Go 建置所需的原生程式庫和模型資源；如已透過其他方式準備好相同資源，可略過此步驟。從倉庫根目錄啟動時，Go 服務會自動尋找 `rag/res/deepdoc`；如需從其他目錄啟動，請將 `DEEPDOC_MODEL_DIR` 設為該目錄的絕對路徑。 +3. 啟動本機依賴服務，並確認 **conf/service_conf.yaml** 中的主機與連接埠可從主機存取： ```bash - export HF_ENDPOINT=https://hf-mirror.com + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` -5. 如果你的操作系统没有 jemalloc，请按照如下方式安装： + + 從原始碼啟動的 Go 服務透過 `localhost:6379` 連線到 Compose 暴露的 Kvrocks；Docker 服務則使用容器網路中的主機名稱。使用提供的設定無需修改 `/etc/hosts`。 +4. 先遷移資料庫，再依序啟動服務。每項命令都要在倉庫根目錄的獨立終端機執行；資料庫遷移完成後可關閉該終端機，其餘四個服務終端機需保持執行： ```bash - # ubuntu - sudo apt-get install libjemalloc-dev - # centos - sudo yum install jemalloc - # mac - brew install jemalloc - ``` -6. 啟動後端服務： + # 終端機 1：遷移資料庫 + ./bin/ragflow_server --migrate - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh + # 終端機 2：Admin，目標連接埠 9381 + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin + + # 終端機 3：Ingestor + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + + # 終端機 4：Syncer + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + + # 終端機 5：API，目標連接埠 9380 + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api ``` -7. 安裝前端依賴： + + 各啟動模式的作用如下： + + - `--migrate`：執行資料庫遷移，完成後退出。 + - `--admin`：啟動 Admin 服務，負責管理和初始化操作。 + - `--ingestor`：啟動 Ingestor 服務，負責資料攝取和解析任務。 + - `--syncer`：啟動 Syncer 服務，負責資料同步任務。 + - `--api`：啟動 API 服務，為 Web、SDK 和外部用戶端提供介面。 + + `RAGFLOW_DEV_MODE=true` 僅供開發環境使用。它會停用程式碼版本與資料庫遷移版本之間的降級檢查，但不會執行遷移或變更資料庫結構，正式環境請勿設定。Admin 應先於其他服務啟動。遷移完成後，`RAGFLOW_DEV_MODE=true bash build.sh --run` 可啟動 Admin、Ingestor 和 API，但不會啟動 Syncer。 +5. 僅在開發前端時安裝 Node.js 和 npm，並啟動 React 前端： ```bash cd web npm install + API_PROXY_SCHEME=go npm run dev ``` -8. 啟動前端服務： + + 在另一個終端機確認 Go API 已就緒： ```bash - npm run dev + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` - 以下界面說明系統已成功啟動：_ + 返回 HTTP 200 表示 API 可以正常回應。開發結束時，在各服務終端機按 `Ctrl+C` 停止對應程序。如需停止相依服務但保留容器，請執行 `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse`；如需移除相依服務容器和 Compose 網路但保留具名資料卷，請執行 `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`。 - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) - -9. 開發完成後停止 RAGFlow 前端和後端服務： - - ```bash - pkill -f "ragflow_server.py|task_executor.py" - ``` +詳情請參閱[從原始碼啟動服務](./docs/develop/launch_ragflow_from_source.md)。 ## 📚 技術文檔 diff --git a/README_zh.md b/README_zh.md index 7afa587585..3dcd4fc5ce 100644 --- a/README_zh.md +++ b/README_zh.md @@ -26,7 +26,7 @@ Static Badge - docker pull infiniflow/ragflow:v0.27.2 + RAGFlow Docker image downloads Latest Release @@ -34,9 +34,6 @@ license - - Ask DeepWiki -

@@ -62,9 +59,7 @@ - 📌 [近期更新](#-近期更新) - 🌟 [主要功能](#-主要功能) - 🔎 [系统架构](#-系统架构) -- 🎬 [自主托管](#-自主托管) -- 🔧 [系统配置](#-系统配置) -- 🔨 [以源代码启动服务](#-以源代码启动服务) +- 🏠 [本地部署](#-本地部署) - 📚 [技术文档](#-技术文档) - 📜 [路线图](#-路线图) - 🏄 [贡献指南](#-贡献指南) @@ -81,6 +76,8 @@ 请登录网址 [https://cloud.ragflow.io](https://cloud.ragflow.io) 体验云服务。 +如果想在本地部署，请参阅[本地部署](#-本地部署)。 +
Chunking demonstration Agentic workflow demonstration @@ -88,23 +85,21 @@ ## 🔥 近期更新 -- 2026-06-15 支持飞书、Discord、Telegram、Line 等多种聊天渠道。 -- 2026-04-24 支持 DeepSeek v4. -- 2026-03-24 发布 [RAGFlow 官方 Skill](https://clawhub.ai/yingfeng/ragflow-skill) — 提供官方 Skill 以通过 OpenClaw 访问 RAGFlow 数据集。 -- 2025-12-26 支持 AI 代理的"记忆"功能。 -- 2025-11-19 支持 Gemini 3 Pro。 -- 2025-11-12 支持从 Confluence、S3、Notion、Discord、Google Drive 进行数据同步。 -- 2025-10-23 支持 MinerU 和 Docling 作为文档解析方法。 -- 2025-10-15 支持可编排的数据管道。 -- 2025-08-08 支持 OpenAI 最新的 GPT-5 系列模型。 -- 2025-08-01 支持 agentic workflow 和 MCP。 -- 2025-05-23 Agent 新增 Python/JS 代码执行器组件。 -- 2025-03-19 PDF 和 DOCX 中的图支持用多模态大模型去解析得到描述。 +- 2026-09-10 支持通过 Sitemap 接入网站内容。 +- 2026-08-19 推出知识编译，支持在文档级和知识库级生成 Wiki、Graph、Tree、PageIndex、Mind Map、Timeline 及 Skills。 +- 2026-08-19 推出 Agentic RAG，支持 Low、Medium、High、Ultra 四种思考模式。 +- 2026-07-02 支持 Google BigQuery 数据源接入与增量同步。 +- 2026-06-29 支持 WhatsApp、钉钉和企业微信聊天渠道。 +- 2026-05-26 新增 Browser 组件，支持 Agent 自主浏览和操作网页。 +- 2026-04-21 提供七种预置数据摄取流水线模板。 +- 2026-04-21 支持 Agent 应用发布、沙箱代码执行与图表生成。 +- 2026-04-21 支持用户级记忆存储和检索。 +更多更新请参阅[完整发布记录](./docs/release_notes.md)。 ## 🎉 关注项目 -⭐️ 点击右上角的 Star 关注 RAGFlow，可以获取最新发布的实时通知 !🌟 +⭐️ 点击右上角的 Star 关注 RAGFlow，可以获取最新发布的实时通知！🌟
RAGFlow feature updates @@ -114,13 +109,32 @@ ### 🍭 **"Quality in, quality out"** -- 基于[深度文档理解](./deepdoc/README.md)，能够从各类复杂格式的非结构化数据中提取真知灼见。 +- 基于深度文档理解，能够从各类复杂格式的非结构化数据中提取真知灼见。 - 真正在无限上下文（token）的场景下快速完成大海捞针测试。 ### 🍱 **基于模板的文本切片** - 不仅仅是智能，更重要的是可控可解释。 -- 多种文本模板可供选择 +- 多种文本模板可供选择。 + +### 🧩 **知识编译（Knowledge Compilation）** + +- 支持文档级和知识库级编译，将原始内容组织为结构化的知识产物。 +- 通过编译模板生成 Wiki、Graph、Tree、PageIndex、Mind Map、Timeline 及 Skills，满足不同的知识组织和复用需求。 +- 支持配置编译模型与处理规则，并查看、更新和重新生成知识产物。 + +### 🧠 **Agentic Retrieval** + +- 面向复杂问题进行多步检索：模型会分析问题，并在需要时执行问题拆解、知识检索和证据核验。 +- 通过多轮检索与推理获取更完整的上下文，帮助生成有依据的回答。 +- 支持 Low、Medium、High、Ultra 思考模式，可按问题复杂度控制检索和推理深度。 + +### ⚙️ **Go 原生服务架构** + +- API、Admin、Ingestor 和 Syncer 由 Go 服务统一提供。 +- DeepDoc 在 Go 进程内运行，负责版面分析、OCR 和表格识别。 +- Go 服务通过 CGO 调用原生文档解析库和 ONNX Runtime。 +- MCP 和 Sandbox Executor 作为可选能力按需启用。 ### 🌱 **有理有据、最大程度降低幻觉（hallucination）** @@ -129,11 +143,11 @@ ### 🍔 **兼容各类异构数据源** -- 支持丰富的文件类型，包括 Word 文档、PPT、excel 表格、txt 文件、图片、PDF、影印件、复印件、结构化数据、网页等。 +- 支持丰富的文件类型，包括 Word 文档、PPT、Excel 表格、TXT 文件、图片、PDF、影印件、复印件、结构化数据、网页等。 ### 🛀 **全程无忧、自动化的 RAG 工作流** -- 全面优化的 RAG 工作流可以支持从个人应用乃至超大型企业的各类生态系统。 +- 自动化的 RAG 工作流可以支持从个人应用乃至超大型企业的各类生态系统。 - 大语言模型 LLM 以及向量模型均支持配置。 - 基于多路召回、融合重排序。 - 提供易用的 API，可以轻松集成到各类企业系统。 @@ -141,26 +155,28 @@ ## 🔎 系统架构
-RAGFlow system architecture + RAGFlow system architecture
-## 🎬 自主托管 +## 🏠 本地部署 -### 📝 前提条件 +本地部署提供 Docker 部署和源码启动两种方式：Docker 适合快速体验、集成测试和生产部署；源码启动适合 Go 服务开发、调试和二次开发。Docker 部署无需安装 Go，源码启动需要安装 `go.mod` 指定的 Go 版本；前端开发还需要 Node.js 和 npm。 -- CPU >= 4 核 -- RAM >= 16 GB -- Disk >= 50 GB -- Docker >= 24.0.0 & Docker Compose >= v2.26.1 -- Python >= 3.13 -- [gVisor](https://gvisor.dev/docs/user_guide/install/): 仅在你打算使用 RAGFlow 的代码执行器（沙箱）功能时才需要安装。 +### 🐳 Docker 部署 -> [!TIP] -> 如果你并没有在本机安装 Docker（Windows、Mac，或者 Linux）, 可以参考文档 [Install Docker Engine](https://docs.docker.com/engine/install/) 自行安装。 +#### 📝 Docker 部署前提条件 -### 🚀 启动服务器 +- 建议起步配置：4 核 CPU、16 GB 内存和 50 GB 可用磁盘。实际资源需求取决于文档引擎、数据规模、解析任务和并发量；启用本地模型或其他额外组件时，请同时满足相应组件的资源要求。 +- Docker ≥ 24.0.0，Docker Compose ≥ v2.26.1。 +- [gVisor](https://gvisor.dev/docs/user_guide/install/)：仅在使用 Self-Managed 容器 Sandbox 时需要安装和配置。 -1. 确保 `vm.max_map_count` 不小于 262144： +Docker 部署无需在宿主机安装 Go。使用 Self-Managed 容器 Sandbox 时需要额外安装和配置 gVisor，其他 Sandbox Provider 不要求在 RAGFlow 主机上安装 gVisor。 + +> ⚠️ **提示：** 如果你尚未在本机安装 Docker（Windows、macOS 或 Linux），可以参考 [Install Docker Engine](https://docs.docker.com/engine/install/) 自行安装。 + +#### 🚀 启动服务器 + +1. 如果使用 Elasticsearch，将 Docker 主机的 `vm.max_map_count` 设置为至少 262144。使用 Infinity 时通常不需要执行此步骤： > 如需确认 `vm.max_map_count` 的大小： > @@ -168,7 +184,7 @@ > sysctl vm.max_map_count > ``` > - > 如果 `vm.max_map_count` 的值小于 262144，可以进行重置： + > 如果使用 Elasticsearch 且 `vm.max_map_count` 的值小于 262144，可以进行重置： > > ```bash > # 这里我们设为 262144: @@ -187,215 +203,156 @@ git clone https://github.com/infiniflow/ragflow.git ``` -3. 进入 **docker** 文件夹，利用提前编译好的 Docker 镜像启动服务器： +3. 构建 Go 版镜像并使用 Go 版 Compose 配置启动服务器： -> [!CAUTION] -> 请注意，目前官方提供的所有 Docker 镜像均基于 x86 架构构建，并不提供基于 ARM64 的 Docker 镜像。 -> 如果你的操作系统是 ARM64 架构，请参考[这篇文档](https://ragflow.io/docs/dev/build_docker_image)自行构建 Docker 镜像。 + > ⚠️ **提示：** Go 镜像的正式构建目标为 `linux/amd64`。详细平台、资源和 macOS 要求请参阅[Go Docker 镜像构建与平台支持说明](./docs/develop/build_docker_image.mdx)。 - > 运行以下命令会自动下载 RAGFlow Docker 镜像 `v0.27.2`。请参考下表查看不同 Docker 发行版的描述。如需下载不同于 `v0.27.2` 的 Docker 镜像，请在运行 `docker compose` 启动服务之前先更新 **docker/.env** 文件内的 `RAGFLOW_IMAGE` 变量。 + > 首次部署需要先构建 Go 镜像，构建时间取决于网络和机器性能。 - ```bash - cd ragflow/docker + 将以下值写入 `docker/.env`： - git checkout v0.27.2 - # 可选：使用稳定版本标签（查看发布：https://github.com/infiniflow/ragflow/releases） - # 这一步确保代码中的 entrypoint.sh 文件与 Docker 镜像的版本保持一致。 - - # Use CPU for DeepDoc tasks: - docker compose -f docker-compose.yml up -d - - # To use GPU to accelerate DeepDoc tasks: - # sed -i '1i DEVICE=gpu' .env - # docker compose -f docker-compose.yml up -d + ```dotenv + RAGFLOW_IMAGE=ragflow:go-local ``` - > 注意：在 `v0.22.0` 之前的版本，我们会同时提供包含 embedding 模型的镜像和不含 embedding 模型的 slim 镜像。具体如下： + ```bash + cd ragflow + docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . + cd docker + docker compose --env-file .env -f docker-compose.yml up -d + ``` - | RAGFlow image tag | Image size (GB) | Has embedding models? | Stable? | - |-------------------|-----------------|-----------------------|----------------| - | v0.21.1 | ≈9 | ✔️ | Stable release | - | v0.21.1-slim | ≈2 | ❌ | Stable release | + 默认 MySQL 配置下，Go 镜像入口会先执行数据库迁移，再通过 `bin/ragflow_server` 启动 Syncer、Admin、API 和 Ingestor。 - > 从 `v0.22.0` 开始，我们只发布 slim 版本，并且不再在镜像标签后附加 **-slim** 后缀。 - - > [!TIP] - > 如果你遇到 Docker 镜像拉不下来的问题，可以在 **docker/.env** 文件内根据变量 `RAGFLOW_IMAGE` 的注释提示选择华为云或者阿里云的相应镜像。 - > - > - 华为云镜像名：`swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow` - > - 阿里云镜像名：`registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow` + > RAGFlow 开源版 1.0 的 DeepDoc 版面分析、OCR 和表格识别使用 CPU 推理。 4. 服务器启动成功后再次确认服务器状态： - ```bash - docker logs -f docker-ragflow-cpu-1 - ``` - - _出现以下界面提示说明服务器启动成功：_ + 使用 `docker compose --env-file .env -f docker-compose.yml ps` 检查依赖服务状态；依赖服务显示 `healthy` 且 RAGFlow 容器持续运行后，通过 HTTP 接口判断 RAGFlow 是否就绪（RAGFlow 容器本身未定义 Compose healthcheck）： ```bash - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) + curl -f http://localhost/api/v1/system/healthz ``` - > 如果您在没有看到上面的提示信息出来之前，就尝试登录 RAGFlow，你的浏览器有可能会提示 `network abnormal` 或 `网络异常`。 + 返回 HTTP 200 后，再访问 Web 页面。如果修改了 `SVR_WEB_HTTP_PORT`，请将健康检查地址中的端口替换为对应值。 + + 如果服务启动异常，再查看对应容器日志： + + ```bash + # CPU 部署 + docker compose --env-file .env -f docker-compose.yml logs --tail 50 ragflow-cpu + + ``` 5. 在你的浏览器中输入你的服务器对应的 IP 地址并登录 RAGFlow。 > 上面这个例子中，您只需输入 http://IP_OF_YOUR_MACHINE 即可：未改动过配置则无需输入端口（默认的 HTTP 服务端口 80）。 -6. 在 [service_conf.yaml.template](./docker/service_conf.yaml.template) 文件的 `user_default_llm` 栏配置 LLM factory，并在 `API_KEY` 栏填写和你选择的大模型相对应的 API key。 +6. 登录 RAGFlow 后，在模型提供商页面添加 LLM、Embedding 和 Reranker，并填写对应的模型名称、服务地址和 API key。 > 详见 [llm_api_key_setup](https://ragflow.io/docs/dev/llm_api_key_setup)。 _好戏开始，接着奏乐接着舞！_ -## 🔧 系统配置 +详情请见 [快速入门指南](./docs/quickstart.mdx)。 -系统配置涉及以下三份文件： +#### ⚙️ Docker 配置与调整 -- [.env](./docker/.env)：存放一些基本的系统环境变量，比如 `SVR_HTTP_PORT`、`MYSQL_PASSWORD`、`MINIO_PASSWORD` 等。 -- [service_conf.yaml.template](./docker/service_conf.yaml.template)：配置各类后台服务。 -- [docker-compose.yml](./docker/docker-compose.yml): 系统依赖该文件完成启动。 +Go 版 Docker 部署使用 `docker/.env` 和 `docker/docker-compose.yml`，使用 Kvrocks 存储缓存和 Checkpoint，并使用 NATS JetStream 作为消息队列。镜像、端口、密码、文档引擎及模型镜像源请按[Docker 配置说明](./docker/README.md)修改；平台限制和 macOS 运行要求请参阅[Go Docker 镜像构建与平台支持指南](./docs/develop/build_docker_image.mdx)。 -请务必确保 [.env](./docker/.env) 文件中的变量设置与 [service_conf.yaml.template](./docker/service_conf.yaml.template) 文件中的配置保持一致！ +切换文档引擎、修改配置后重启服务，以及保留或清理已有数据的操作，也请按照上述 Docker 配置文档执行。 -如果不能访问镜像站点 hub.docker.com 或者模型站点 huggingface.co，请按照 [.env](./docker/.env) 注释修改 `RAGFLOW_IMAGE` 和 `HF_ENDPOINT`。 +### 🔨 以源代码启动 Go 服务 -> [./docker/README](./docker/README.md) 解释了 [service_conf.yaml.template](./docker/service_conf.yaml.template) 用到的环境变量设置和服务配置。 +#### 📝 源码启动前提条件 -如需更新默认的 HTTP 服务端口(80), 可以在 [docker-compose.yml](./docker/docker-compose.yml) 文件中将配置 `80:80` 改为 `:80`。 +源码启动请安装 `go.mod` 中指定的 Go 版本（当前为 Go 1.27）、Clang 20、LLD 20、CMake ≥ 4.0、PCRE2 开发文件和 CGO 所需的原生库。仅开发 React 前端时需要 Node.js 和 npm。 -> 所有系统配置都需要通过系统重启生效： -> -> ```bash -> docker compose -f docker-compose.yml up -d -> ``` - -### 把文档引擎从 Elasticsearch 切换成为 Infinity - -RAGFlow 默认使用 Elasticsearch 存储文本和向量数据. 如果要切换为 [Infinity](https://github.com/infiniflow/infinity/), 可以按照下面步骤进行: - -1. 停止所有容器运行: - - ```bash - docker compose -f docker/docker-compose.yml down -v - ``` - Note: `-v` 将会删除 docker 容器的 volumes，已有的数据会被清空。 - -2. 设置 **docker/.env** 目录中的 `DOC_ENGINE` 为 `infinity`. - -3. 启动容器: - - ```bash - docker compose -f docker/docker-compose.yml up -d - ``` - -> [!WARNING] -> Infinity 目前官方并未正式支持在 Linux/arm64 架构下的机器上运行. - -## 🔧 源码编译 Docker 镜像 - -本 Docker 镜像大小约 2 GB 左右并且依赖外部的大模型和 embedding 服务。 - -```bash -git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ -docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -如果您处在代理环境下，可以传递代理参数： - -```bash -docker build --platform linux/amd64 \ - --build-arg http_proxy=http://YOUR_PROXY:PORT \ - --build-arg https_proxy=http://YOUR_PROXY:PORT \ - -f Dockerfile -t infiniflow/ragflow:nightly . -``` - -## 🔨 以源代码启动服务 - -1. 安装 `uv`。如已经安装，可跳过本步骤： - - ```bash - pipx install uv - export UV_INDEX=https://mirrors.aliyun.com/pypi/simple - ``` - -2. 下载源代码并安装 Python 依赖： +1. 克隆仓库，并安装 `go.mod` 中指定的 Go 版本（当前为 Go 1.27）、Clang 20、LLD 20、CMake ≥ 4.0，以及 PCRE2 开发文件。Go 服务依赖 CGO 和原生静态库；[build.sh](./build.sh) 会设置所需的构建参数。 ```bash git clone https://github.com/infiniflow/ragflow.git - cd ragflow/ - uv sync --python 3.13 # install RAGFlow dependent python modules - uv run python3 ragflow_deps/download_deps.py - git config --local --unset core.hooksPath - uv tool install lefthook - lefthook install + cd ragflow ``` -3. 通过 Docker Compose 启动依赖的服务（MinIO, Elasticsearch, Redis, and MySQL）： +2. 按 [Go 依赖下载脚本](./ragflow_deps/download_go_deps.py)准备原生库和模型文件，再编译 Go 服务： ```bash - docker compose -f docker/docker-compose-base.yml up -d + python3 -m venv /tmp/ragflow-go-download-venv + /tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub + /tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py + bash build.sh --all ``` - 在 `/etc/hosts` 中添加以下代码，目的是将 **conf/service_conf.yaml** 文件中的所有 host 地址都解析为 `127.0.0.1`： + 下载脚本负责准备 Go 构建所需的原生库和模型资源，并需要 `requests` 和 `huggingface-hub`。如果已通过其他方式准备好相同资源，可跳过这一步。Go 服务从仓库根目录启动时会自动查找 `rag/res/deepdoc`；如需从其他目录启动，请将 `DEEPDOC_MODEL_DIR` 设为该目录的绝对路径。 - ```text - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager - ``` -4. 如果无法访问 HuggingFace，可以把环境变量 `HF_ENDPOINT` 设成相应的镜像站点： +3. 启动本地依赖服务，并确认 **conf/service_conf.yaml** 中的主机与端口对应宿主机可访问的地址。Go 源码服务通过 `localhost:6379` 连接 Compose 暴露的 Kvrocks；Go Docker 服务则在容器网络中连接 Kvrocks。如果使用默认 Elasticsearch，还需先将 Docker 主机的 `vm.max_map_count` 设为至少 `262144`。 ```bash - export HF_ENDPOINT=https://hf-mirror.com + sudo sysctl -w vm.max_map_count=262144 + docker compose --env-file docker/.env -f docker/docker-compose-base.yml \ + up -d --wait es01 mysql minio nats kvrocks clickhouse ``` -5. 如果你的操作系统没有 jemalloc，请按照如下方式安装： +4. 先迁移数据库，再分别在 5 个独立终端中按顺序启动 Go 服务（命令均在仓库根目录运行）。每次只在对应终端中执行该终端下方的命令，不要把所有命令一次性粘贴到同一个终端。迁移命令无需设置 `RAGFLOW_DEV_MODE`；开发环境中的 Admin、Ingestor、Syncer 和 API 按下方命令设置 `RAGFLOW_DEV_MODE=true`。迁移命令执行完成后即可关闭终端，其他 4 个服务终端需要保持运行。 + + 终端 1：迁移数据库。 ```bash - # ubuntu - sudo apt-get install libjemalloc-dev - # centos - sudo yum install jemalloc - # mac - brew install jemalloc + ./bin/ragflow_server --migrate ``` -6. 启动后端服务： + 终端 2：启动 Admin（目标端口 `9381`）。 ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - bash docker/launch_backend_service.sh + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin ``` -7. 安装前端依赖： + 终端 3：启动 Ingestor。 + + ```bash + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor + ``` + + 终端 4：启动 Syncer。 + + ```bash + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer + ``` + + 终端 5：启动 API（目标端口 `9380`）。 + + ```bash + RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api + ``` + + 各启动模式的作用如下： + + - `--migrate`：执行数据库迁移，完成后即可退出。 + - `--admin`：启动 Admin 服务，负责管理和初始化操作。 + - `--ingestor`：启动 Ingestor 服务，负责数据摄取和解析任务。 + - `--syncer`：启动 Syncer 服务，负责数据同步任务。 + - `--api`：启动 API 服务，为 Web、SDK 和外部客户端提供接口。 + + `RAGFLOW_DEV_MODE=true` 仅用于开发环境关闭代码版本与数据库迁移版本之间的降级检查，不会执行迁移或改变数据库结构，生产部署不要设置此变量。Admin 应先于其他服务启动。数据库迁移完成后，`RAGFLOW_DEV_MODE=true bash build.sh --run` 可作为便捷方式启动 Admin、Ingestor 和 API；该命令不启动 Syncer，需要完整服务链路时仍应另行执行 `RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer`。 + +5. 仅在前端开发时安装 Node.js 和 npm，然后启动 React 前端： ```bash cd web npm install + API_PROXY_SCHEME=go npm run dev ``` -8. 启动前端服务： + 服务启动后，在另一个终端确认 Go API 已就绪： ```bash - npm run dev + curl -f http://127.0.0.1:9380/api/v1/system/healthz ``` - _以下界面说明系统已经成功启动：_ + 返回 HTTP 200 表示 API 可以正常响应。前端、ClickHouse 和 DeepDoc 的完整验证步骤请参阅[从源代码启动服务](./docs/develop/launch_ragflow_from_source.md#5-verify-the-startup)。 - ![RAGFlow web interface](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) - -9. 开发完成后停止 RAGFlow 前端和后端服务： - - ```bash - pkill -f "ragflow_server.py|task_executor.py" - ``` + 开发结束时，在各服务终端按 `Ctrl+C` 停止进程。如需停止依赖但保留容器以便下次使用，运行 `docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop es01 mysql minio nats kvrocks clickhouse`；如需删除依赖容器和 Compose 网络但保留命名数据卷，运行 `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`。 +详情请见 [从源代码启动服务](./docs/develop/launch_ragflow_from_source.md)。 ## 📚 技术文档 @@ -419,7 +376,7 @@ docker build --platform linux/amd64 \ ## 🙌 贡献指南 -RAGFlow 只有通过开源协作才能蓬勃发展。秉持这一精神,我们欢迎来自社区的各种贡献。如果您有意参与其中,请查阅我们的 [贡献者指南](https://ragflow.io/docs/dev/contributing) 。 +RAGFlow 只有通过开源协作才能蓬勃发展。秉持这一精神，我们欢迎来自社区的各种贡献。如果您有意参与其中，请查阅我们的[贡献者指南](https://ragflow.io/docs/dev/contributing)。 ## 🤝 商务合作 diff --git a/docker/README.md b/docker/README.md index fe4b3c9068..8019d99e05 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,7 +1,11 @@ -# README +# Go Docker deployment + +This guide documents the Go implementation of RAGFlow. Use `docker/.env`, `docker/docker-compose.yml`, `Dockerfile`, and `docker/entrypoint.sh` for a Go deployment. + +The Go image runs the API, Admin, Ingestor, and Syncer modes from the single `bin/ragflow_server` binary. DeepDoc inference runs in-process. Select an official Go image tag documented in the corresponding release notes, or build the image locally as described below.
-📗 Table of Contents +📗 Table of Contents - 🐳 [Docker Compose](#-docker-compose) - 🐬 [Docker environment variables](#-docker-environment-variables) @@ -13,27 +17,65 @@ ## 🐳 Docker Compose - **docker-compose.yml** - Sets up environment for RAGFlow and its dependencies. + Starts the Go RAGFlow container together with the selected dependencies. - **docker-compose-base.yml** - Sets up environment for RAGFlow's dependencies: Elasticsearch/[Infinity](https://github.com/infiniflow/infinity), MySQL, MinIO, and Redis. + Defines the dependency services. The default Go profile uses Elasticsearch, MySQL, MinIO, Kvrocks, NATS, and ClickHouse. Other document engines and metadata databases are selected through `.env`. -> [!CAUTION] -> We do not actively maintain **docker-compose-CN-oc9.yml**, **docker-compose-macos.yml**, so use them at your own risk. However, you are welcome to file a pull request to improve any of them. +> **Note:** `docker-compose-CN-oc9.yml` and `docker-compose-macos.yml` are not the Go deployment entry points. On Linux and macOS, use `docker-compose.yml`; Apple Silicon runs the current `linux/amd64` Go image through Docker Desktop emulation. + +### Quick start + +Run these commands from the repository root. The `.git` directory must remain in the build context because `Dockerfile` uses it to stamp the image version. + +```bash +docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . +``` + +Set the image in `docker/.env`: + +```dotenv +RAGFLOW_IMAGE=ragflow:go-local +``` + +If you use the default Elasticsearch document engine on Linux, set `vm.max_map_count` to at least `262144` on the Docker host: + +```bash +sudo sysctl -w vm.max_map_count=262144 +``` + +This change is temporary. To preserve it after a reboot, add `vm.max_map_count=262144` to `/etc/sysctl.conf`. On Docker Desktop, apply the setting inside its Linux virtual machine as described in the [Go image build guide](../docs/develop/build_docker_image.mdx#macos-with-docker-desktop). + +Start the default CPU stack: + +```bash +cd docker +docker compose --env-file .env -f docker-compose.yml up -d +``` + +The entrypoint migrates the default MySQL metadata database first, then starts the Go Syncer, Admin server, API server, and Ingestor. Open `http://localhost` after the HTTP health check succeeds. + +Verify the deployment with: + +```bash +docker compose --env-file .env -f docker-compose.yml ps +docker compose --env-file .env -f docker-compose.yml logs --tail 100 ragflow-cpu +curl -f http://localhost/api/v1/system/healthz +``` + +If `SVR_WEB_HTTP_PORT` is not `80`, append the configured port to the URL. In the RAGFlow open-source 1.0 release, DeepDoc layout analysis, OCR, and table recognition use CPU inference. ## 🐬 Docker environment variables -The [.env](./.env) file contains important environment variables for Docker. +The [.env](./.env) file is the user-facing environment file for the Go deployment. Compose also loads shared defaults from [.env](./.env) for included dependency definitions. When a dependency setting exists in both files, keep the credentials and published ports consistent. ### Metadata database - `DB_TYPE` - The business metadata database type. Defaults to `mysql`. Supported values include `mysql`, `postgres`, `gaussdb`, and `oceanbase`. + The business metadata database type. Defaults to `mysql`. Set it to `oceanbase` when connecting to OceanBase through its MySQL-compatible protocol. - `COMPOSE_PROFILES` - The Docker Compose profiles to enable. By default it contains `${DOC_ENGINE},${DEVICE},metadata-${METADATA_DB_PROFILE}`. + The Docker Compose profiles to enable. By default it contains `${DOC_ENGINE},${DEVICE},metadata-${METADATA_DB_PROFILE},ragflow-go,clickhouse`. - `METADATA_DB_PROFILE` - Defaults to `mysql`, preserving the in-cluster MySQL service. Set it to `gaussdb` together with `DB_TYPE=gaussdb` to use an external GaussDB metadata database without starting MySQL. -- `GAUSSDB_METADATA_HOST`, `GAUSSDB_METADATA_PORT`, `GAUSSDB_METADATA_USER`, `GAUSSDB_METADATA_PASSWORD`, `GAUSSDB_METADATA_DBNAME`, `GAUSSDB_METADATA_SCHEMA` - External GaussDB metadata database connection settings, used when `DB_TYPE=gaussdb`. Set `METADATA_DB_PROFILE=gaussdb` to keep the in-cluster MySQL service disabled. + Defaults to `mysql`, preserving the in-cluster MySQL service. ### Elasticsearch @@ -47,12 +89,12 @@ The [.env](./.env) file contains important environment variables for Docker. ### Kibana - `KIBANA_PORT` - The port used to expose the Kibana service to the host machine, allowing **external** access to the service running inside the Docker container. Defaults to `6601`. + The port used to expose the optional Kibana service to the host machine. Defaults to `6601`. Follow the enablement notes in `.env` before adding the `kibana` profile. ### Resource management - `MEM_LIMIT` - The maximum amount of the memory, in bytes, that *a specific* Docker container can use while running. Defaults to `8073741824`. + The maximum memory available to each Compose service that applies this limit. It is a per-container upper limit, not the minimum host memory, the total memory reserved by RAGFlow, or a guarantee that every container consumes this amount. The default is `8073741824` bytes, approximately `7.52 GiB` (`8.07 GB`). ### MySQL @@ -61,7 +103,9 @@ The [.env](./.env) file contains important environment variables for Docker. - `MYSQL_PORT` The port to connect to MySQL from RAGFlow container. Defaults to `3306`. Change this if you use an external MySQL. - `EXPOSE_MYSQL_PORT` - The port used to expose the MySQL service to the host machine, allowing **external** access to the MySQL database running inside the Docker container. Defaults to `5455`. + The port used to expose the MySQL service to the host machine, allowing **external** access to the MySQL database running inside the Docker container. Defaults to `3306`. +- `MYSQL_MAX_PACKET` + The maximum MySQL communication packet size in bytes. Defaults to `1073741824` bytes (`1 GiB`). Keep the MySQL server's `max_allowed_packet` setting compatible when using an external database. ### MinIO @@ -74,23 +118,47 @@ The [.env](./.env) file contains important environment variables for Docker. - `MINIO_PASSWORD` The password for MinIO. -### Redis +### Kvrocks -- `REDIS_PORT` - The port used to expose the Redis service to the host machine, allowing **external** access to the Redis service running inside the Docker container. Defaults to `6379`. +The Go services use Kvrocks as their Redis-compatible cache. NATS JetStream provides the message queue. + +- `KVROCKS_HOST` + The hostname used by the Go services. Keep the default `kvrocks` for the Compose deployment. +- `KVROCKS_PORT` + The host-published Kvrocks port. Defaults to `6379`. - `REDIS_PASSWORD` - The password for Redis. + The password shared with the Kvrocks service. + +### NATS + +The Go services use NATS JetStream for ingestion, synchronization, memory, and knowledge-compilation messages. + +- `NATS_HOST` + The NATS hostname used inside the Compose network. Defaults to `nats`. +- `NATS_PORT` + The internal NATS client port. Defaults to `4222`. +- `EXPOSE_NATS_PORT` + The port published on the Docker host. Change this value to avoid a host-side port conflict; Go containers continue to use `NATS_PORT` internally. ### RAGFlow - `SVR_HTTP_PORT` - The port used to expose RAGFlow's HTTP API service to the host machine, allowing **external** access to the service running inside the Docker container. Defaults to `9380`. + The target Go API port published by Compose. Defaults to `9380`; Nginx proxies normal web API requests to this service. +- `ADMIN_SVR_HTTP_PORT` + The target Go Admin port published by Compose. Defaults to `9381`. +- `SVR_WEB_HTTP_PORT`, `SVR_WEB_HTTPS_PORT` + The public Nginx ports. Defaults to `80` and `443`. +- `RAGFLOW_DEV_MODE` + Set to `true` only for development checkouts that intentionally use a development migration marker. Keep it `false` in production. - `RAGFLOW_IMAGE` - The Docker image edition. Defaults to `infiniflow/ragflow:v0.27.2`. The RAGFlow Docker image does not include embedding models. + The Go Docker image used by `docker-compose.yml`. Use an official Go image tag documented in its release notes, or use the locally built `ragflow:go-local` tag. The RAGFlow Docker image does not include embedding models. + +### Local embedding service + +The optional `tei-cpu` and `tei-gpu` profiles start a local text-embeddings-inference service. Its memory requirement depends on the model, runtime backend, precision, batch-token limit, and concurrency. The `tei-cpu` profile uses system RAM; the `tei-gpu` profile primarily uses GPU memory and also consumes system RAM. Verify model loading and peak request usage on the target hardware, and leave additional host memory for RAGFlow, the document engine, databases, and operating system. -> [!TIP] -> If you cannot download the RAGFlow Docker image, try the following mirrors. +> 💡 **Tip:** If you cannot download a Go RAGFlow Docker image, try the following mirrors. > > - For the `nightly` edition: > - `RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:nightly` or, @@ -98,13 +166,9 @@ The [.env](./.env) file contains important environment variables for Docker. ### DeepDoc (in-process) -DeepDoc layout analysis (DLA), OCR (text detection/recognition), and table -structure recognition (TSR) run **in-process** inside the RAGFlow server using -ONNX Runtime — there is no separate DeepDoc service to deploy. ONNX Runtime is -statically linked into the server binary (resolved at runtime via dlopen(NULL); -no `libonnxruntime.so` is required) and the models are loaded at runtime; -`DEEPDOC_MODEL_DIR` overrides the default model directory, which falls back to -the `ragflow_deps/download_deps.py` snapshot. +DeepDoc layout analysis (DLA), OCR (text detection/recognition), and table structure recognition (TSR) run **in-process** inside the RAGFlow server using ONNX Runtime — there is no separate DeepDoc service to deploy. ONNX Runtime is statically linked into the server binary (resolved at runtime via dlopen(NULL); no `libonnxruntime.so` is required) and the models are loaded at runtime; `DEEPDOC_MODEL_DIR` overrides the default model directory. `Dockerfile` copies the required model assets into `/ragflow/rag/res/deepdoc`. + +In the RAGFlow open-source 1.0 release, DeepDoc uses CPU inference. ### Timezone @@ -116,81 +180,31 @@ the `ragflow_deps/download_deps.py` snapshot. - `HF_ENDPOINT` The mirror site for huggingface.co. It is disabled by default. You can uncomment this line if you have limited access to the primary Hugging Face domain. -### MacOS - -- `MACOS` - Optimizations for macOS. It is disabled by default. You can uncomment this line if your OS is macOS. - -### Maximum file size - -- `MAX_CONTENT_LENGTH` - The maximum file size for each uploaded file, in bytes. You can uncomment this line if you wish to change the 128M file size limit. After making the change, ensure you update `client_max_body_size` in nginx/nginx.conf correspondingly. - -### Doc bulk size - -- `DOC_BULK_SIZE` - The number of document chunks processed in a single batch during document parsing. Defaults to `4`. - ### Embedding batch size -- `EMBEDDING_BATCH_SIZE` - The number of text chunks processed in a single batch during embedding vectorization. Defaults to `16`. - -### OceanBase prerequisites - -Before setting `DOC_ENGINE=oceanbase`, make sure the host OS allows the file descriptor and core dump limits OceanBase expects. - -1. Set host limits: - - ```bash - sudo tee /etc/security/limits.d/99-oceanbase.conf >/dev/null <<'EOF' - root soft nofile 655350 - root hard nofile 655350 - * soft nofile 655350 - * hard nofile 655350 - * soft core unlimited - * hard core unlimited - EOF - ``` - -2. Make sure PAM limits are enabled: - - ```bash - grep -E 'pam_limits\.so' /etc/pam.d/common-session /etc/pam.d/common-session-noninteractive - ``` - - If missing, add them: - - ```bash - echo 'session required pam_limits.so' | sudo tee -a /etc/pam.d/common-session - echo 'session required pam_limits.so' | sudo tee -a /etc/pam.d/common-session-noninteractive - ``` - -3. Log out and log back in, or reboot. - -4. Verify the effective limit: - - ```bash - ulimit -n - ``` - - Expected: `655350`, or at least `20000`. +- `TOKENIZER_EMBEDDING_BATCH_SIZE` + An optional positive integer that overrides the number of text chunks sent in each embedding request. When it is not set, RAGFlow uses the embedding model's batch size, or `16` if the model does not provide one. Larger values can increase memory usage and may exceed the model provider's request limit; increase it gradually and verify parsing on representative documents. ## 🐋 Service configuration -[service_conf.yaml.template](./service_conf.yaml.template) specifies the system-level configuration for RAGFlow and is used by its API server and task executor. In a dockerized setup, the generated `service_conf.yaml` file is automatically created from this template (replacing all environment variables by their values). +[service_conf.yaml.template](./service_conf.yaml.template) specifies the system-level configuration for the Go API, Admin, Ingestor, and Syncer services. In a dockerized setup, the generated `service_conf.yaml` file is automatically created from this template (replacing all environment variables by their values). - `ragflow` - `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`. +- `admin` + - `host`: The Admin server's IP address inside the Docker container. Defaults to `0.0.0.0`. + - `http_port`: The Admin server's serving port inside the Docker container. Defaults to `9381`. + - `mysql` - `name`: The MySQL database name. Defaults to `rag_flow`. - `user`: The username for MySQL. - `password`: The password for MySQL. - `port`: The MySQL serving port inside the Docker container. Defaults to `3306`. - - `max_connections`: The maximum number of concurrent connections to the MySQL database. Defaults to `100`. - - `stale_timeout`: Timeout in seconds. + - `max_connections`: The maximum number of concurrent connections in the MySQL connection pool. Defaults to `900`. + - `stale_timeout`: The connection stale timeout in seconds. Defaults to `300`. + - `max_allowed_packet`: The maximum communication packet size. Defaults to `1073741824` bytes (`1 GiB`). - `minio` - `user`: The username for MinIO. @@ -206,15 +220,6 @@ Before setting `DOC_ENGINE=oceanbase`, make sure the host OS allows the file des - `host`: The hostname of the OceanBase service. - `port`: The port of OceanBase. -- `gaussdb` - - `host`: The hostname or IP address of the GaussDB instance. - - `port`: The GaussDB port. - - `database`: The GaussDB database name. Defaults to `postgres`. - - `user`: The username for GaussDB. - - `password`: The password for GaussDB. - - `schema`: Optional schema used by the DocEngine. Defaults to `public`. - - RAGFlow does not start or manage GaussDB; set `DOC_ENGINE=gaussdb` only after preparing a GaussDB instance. - - `oss` - `access_key`: The access key ID used to authenticate requests to the OSS service. - `secret_key`: The secret access key used to authenticate requests to the OSS service. @@ -248,21 +253,6 @@ Before setting `DOC_ENGINE=oceanbase`, make sure the host OS allows the file des - `scope`: Requested permission scope, a space-separated string. For example, `openid profile email`. - `redirect_uri`: Required, URI to which the authorization server redirects during the authentication flow to return results. Must match the callback URI registered with the authentication server. Format: `https://your-app.com/api/v1/auth/oauth//callback`. For local configuration, you can directly use `http://127.0.0.1:80/api/v1/auth/oauth//callback`. -- `user_default_llm` - The default LLM to use for a new RAGFlow user. It is disabled by default. To enable this feature, uncomment the corresponding lines in **service_conf.yaml.template**. - - `factory`: The LLM supplier. Available options: - - `"OpenAI"` - - `"DeepSeek"` - - `"Moonshot"` - - `"Tongyi-Qianwen"` - - `"VolcEngine"` - - `"ZHIPU-AI"` - - `api_key`: The API key for the specified LLM. You will need to apply for your model API key online. - -> [!TIP] -> If you do not set the default LLM here, configure the default LLM on the **Settings** page in the RAGFlow UI. - - ## 📋 Setup Examples ### 🔒 HTTPS Setup @@ -295,10 +285,10 @@ If you want your instance to be available under `https`, follow these steps: - Private key: `/etc/letsencrypt/live/your-ragflow-domain.com/privkey.pem` 3. **Update docker-compose.yml** - Add the certificate volumes to the `ragflow` service in your `docker-compose.yml`: + Add the certificate volumes to the `ragflow-cpu` service in `docker-compose.yml`: ```yaml services: - ragflow: + ragflow-cpu: # ...existing configuration... volumes: # SSL certificates @@ -315,17 +305,16 @@ If you want your instance to be available under `https`, follow these steps: 5. **Restart the services** ```bash - docker-compose down - docker-compose up -d + docker compose --env-file .env -f docker-compose.yml down + docker compose --env-file .env -f docker-compose.yml up -d ``` -> [!IMPORTANT] -> - Ensure your domain's DNS A record points to your server's IP address -> - Stop any services running on ports 80/443 before obtaining certificates with `--standalone` +> ⚠️ **Important：** +> - Ensure your domain's DNS A record points to your server's IP address. +> - Stop any services running on ports 80/443 before obtaining certificates with `--standalone`. -> [!TIP] -> For development or testing, you can use self-signed certificates, but browsers will show security warnings. +> 💡 **Tip：** For development or testing, you can use self-signed certificates, but browsers will show security warnings. #### Alternative: Using existing certificates diff --git a/docs/administrator/admin/admin_service.md b/docs/administrator/admin/admin_service.md index e4b4df1943..c58951cc56 100644 --- a/docs/administrator/admin/admin_service.md +++ b/docs/administrator/admin/admin_service.md @@ -9,34 +9,108 @@ sidebar_custom_props: { --- # Admin Service -The Admin Service is the core backend management service of the RAGFlow system, providing comprehensive system administration capabilities through centralized API interfaces for managing and controlling the entire platform. Adopting a client-server architecture, it supports access and operations via both a Web UI and an Admin CLI, ensuring flexible and efficient execution of administrative tasks. +The Go Admin Service provides the administration API used by the Web UI and the Go CLI. It manages users and configuration, checks infrastructure dependencies, and tracks Go API servers, ingestors, and file syncers that report heartbeats. The target Admin Service port is `9381`; the target Go API server port is `9380`. -The core functions of the Admin Service include real-time monitoring of the operational status of the RAGFlow server and its critical dependent components—such as MySQL, Elasticsearch, Redis, and MinIO—along with full-featured user management. In administrator mode, it enables key operations such as viewing user information, creating users, updating passwords, modifying activation status, and performing complete user data deletion. These functions remain accessible via the Admin CLI even when the web management interface is disabled, ensuring the system stays under control at all times. +Start the Admin Service before the API server, ingestors, and syncers so those processes can report their heartbeats as soon as they start. MySQL, the configured document engine and storage service, the cache, and the message queue must be available to the Admin Service. For the default host-run configuration, see [Start supporting services](../../develop/launch_ragflow_from_source.md#2-start-supporting-services) for the dependency list, port settings, and readiness checks. -With its unified interface design, the Admin Service combines the convenience of visual administration with the efficiency and stability of command-line operations, serving as a crucial foundation for the reliable operation and secure management of the RAGFlow system. +## Start from source -## Starting the Admin Service +For a fresh checkout, prepare the native dependencies and build the C++ bindings and Go binaries as described in [Get the source and build dependencies](../../develop/launch_ragflow_from_source.md#1-get-the-source-and-build-dependencies): -### Launching from Source Code +```bash +bash build.sh --all +``` -1. Before start Admin Service, please make sure RAGFlow system is already started. +Use `bash build.sh --go` for subsequent Go-only rebuilds after the C++ bindings have already been built. -2. Launch from source code: +Before proceeding, run `./bin/ragflow_server --admin --help` to check that the binary can load and parse the Admin arguments. This command prints help and exits; it does not start the Admin Service or test its dependencies. If it exits with status `139` without printing help, see the [build troubleshooting notes](../../develop/launch_ragflow_from_source.md#1-get-the-source-and-build-dependencies). - ```bash - python admin/server/admin_server.py - ``` +Complete the standalone database migration before starting any server mode. Run the migration once for this startup; do not attach `--migrate` to `--admin`, `--api`, or `--ingestor`: - The service will start and listen for incoming connections from the CLI on the configured port. +```bash +./bin/ragflow_server --migrate +``` -### Using Docker Image +Start each process in a separate terminal, in this order. The source-development commands below use `RAGFLOW_DEV_MODE=true` to bypass the code and database version downgrade check; this setting does not run migrations or change the schema. Do not set it in production: -1. Before startup, please configure the `docker_compose.yml` file to enable admin server: +```bash +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin +``` - ```bash - command: - - --enable-adminserver - ``` +```bash +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api +``` -2. Start the containers, the service will start and listen for incoming connections from the CLI on the configured port. +```bash +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor +``` +If file synchronization is enabled, also start: + +```bash +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer +``` + +To initialize the default superuser when starting Admin, add `--init-superuser` to the Admin command. Do this only when initial account setup is required. + +```bash +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin --init-superuser +``` + +If no superuser exists, this option currently creates `admin@ragflow.io` with the initial password `admin`. Change that password immediately after the first login. It does not reset the password of an existing superuser. + +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. + +## Start with Docker Compose + +For the Go deployment, use `docker/docker-compose.yml` and its `.env` file. The `ragflow-cpu` service already passes `--enable-adminserver` and `--init-superuser` to the Go entrypoint. The entrypoint runs migrations before starting the server processes; it then starts Admin before the API server and ingestor. Its optional syncer starts earlier, so its heartbeat may appear only after Admin becomes available. + +```bash +docker compose --env-file docker/.env -f docker/docker-compose.yml --profile cpu up -d +``` + +The Go Compose deployment exposes the Admin Service on `9381` and the API server on `9380` by default. Use `ADMIN_SVR_HTTP_PORT` and `SVR_HTTP_PORT` to change the corresponding published host ports. + +Use the Go Compose entry point documented in [Go Docker deployment](../../../docker/README.md). Initialize the first superuser with `--init-superuser` only when initial account setup is required. + +## Check health and service registration + +Use `/live` to check whether the Admin HTTP process is responding: + +```bash +curl -f http://127.0.0.1:9381/live +``` + +Use `/healthz` to check the Admin Service and its required dependencies. It returns HTTP `200` when the database, cache, document engine, storage, and message queue are healthy; otherwise it returns HTTP `500` with component status information. + +```bash +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 ` to the CLI command: + +```bash +./bin/ragflow-cli --admin +``` + +```text +RAGFlow(admin)> LOGIN ADMIN 'admin@ragflow.io'; +``` + +The CLI prompts for the password. + +If this is the first login using the initial `admin` password, change it before continuing: + +```text +RAGFlow(admin)> ALTER USER PASSWORD 'admin@ragflow.io' ''; +``` + +Then inspect the registered services: + +```text +RAGFlow(admin)> LIST SERVICES; +``` + +Look for `api_server`, `ingestor`, and, when enabled, `file_syncer` entries with `status=alive`. A previously registered process can remain listed with `status=timeout` after its heartbeats stop. `LIST SERVICES;` also includes health checks for infrastructure dependencies. The CLI commands `LIST API SERVER;` and `SHOW API SERVER '';` inspect locally saved API connection settings, not this heartbeat registry. diff --git a/docs/administrator/admin/admin_ui/before_you_begin.md b/docs/administrator/admin/admin_ui/before_you_begin.md index 31eae39255..e5df2b8ab1 100644 --- a/docs/administrator/admin/admin_ui/before_you_begin.md +++ b/docs/administrator/admin/admin_ui/before_you_begin.md @@ -18,15 +18,8 @@ Regular users do not need to enter the Admin UI when they use business features ## Initial Administrator Account -After the first deployment, you can log in with the default administrator account `admin@ragflow.io`. Its password is chosen when the admin server starts and no superuser exists yet: - -- If the `ADMIN_DEFAULT_PASSWORD` environment variable is set (or `DEFAULT_SUPERUSER_PASSWORD`, which is shared with the web service bootstrap), that value is used. -- Otherwise a random password is generated and written **once** to `logs/admin_bootstrap_password.txt` (mode 0600; in a docker deployment check the `docker/ragflow-logs` volume) — retrieve it from that file, log in, and change it immediately. +When the Admin service starts with `--init-superuser` and no superuser exists, it creates the default administrator account `admin@ragflow.io` with the initial password `admin`. The option does not change an existing superuser account or reset its password. This account is used to initialize the system and create subsequent administrator accounts. It is not recommended as a long-term shared daily operations account. After the first login, reset the default password as soon as possible and create separate accounts for different administrators. In daily administration, grant the `Superuser` identity only to users who actually need Admin UI responsibilities. - -## Change the Admin Account Password - -This feature is not available yet. diff --git a/docs/administrator/admin/admin_ui/check_system_status.md b/docs/administrator/admin/admin_ui/check_system_status.md index 3bfa93725d..96256308c2 100644 --- a/docs/administrator/admin/admin_ui/check_system_status.md +++ b/docs/administrator/admin/admin_ui/check_system_status.md @@ -8,40 +8,45 @@ title: Check System Status ## Check Whether Services Are Running Normally -After entering the Admin UI, open the **Service status** page to view the runtime status of RAGFlow and its dependent services. The page displays each service's name, service type, host, port, and current status, so administrators can confirm whether all system components are running normally. +After entering the Admin UI, open the **Service status** page to view the status reported by the Go services and their configured dependencies. Each row contains the service type, name, host, port, status, an `elapsed` diagnostic value, and an optional message. ![Check Whether Services Are Normal](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/check_whether_services_are_normal.jpg) -When **Status** is `Alive`, the service is running normally. Any other status may affect the corresponding features. +For dependencies, `alive` means that the corresponding health check succeeded. `timeout`, `not available`, or another status indicates that the check failed or that the configured implementation is unavailable. For Go server processes, `alive` means that Admin received a heartbeat during the preceding 45 seconds; otherwise the status is `timeout`. ![System Status](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/system_status.jpg) -| Service name | Main purpose | Possible issues when abnormal | Affected features | -| --- | --- | --- | --- | -| RAGFlow Server | Core system service responsible for the Web UI, APIs, knowledge bases, Q&A, Agent, and other business features. | The system cannot be accessed, login fails, pages report errors, or all features become unavailable. | Login, knowledge base management, knowledge applications, Agent, model management, system management, and all other features. | -| MySQL | Stores business data such as users, knowledge bases, model configurations, and system configurations. | Login fails, knowledge base data cannot be read, configurations cannot be saved, or business data becomes abnormal. | User management, knowledge base management, model configuration, system configuration, and business data reads and writes. | -| MinIO | Stores uploaded documents, images, and other object files. | File upload fails, documents cannot be opened, parsing fails, or images cannot be displayed. | File upload, document management, document parsing, file preview, and download. | -| Elasticsearch | Builds full-text and vector indexes and provides knowledge retrieval capabilities. | Documents cannot be retrieved, searches return no results, Q&A cannot cite knowledge, or knowledge recall is abnormal. | Full-text retrieval, vector retrieval, hybrid retrieval, knowledge Q&A, and knowledge citation. | -| Redis (Valkey) | Provides cache and task status management to improve system runtime efficiency. | Pages respond slowly, sessions become abnormal, or some features run abnormally. | System cache, session management, task status management, and some backend features. | -| RabbitMQ | Manages backend asynchronous tasks and sends tasks to executors. | Documents remain in `Waiting for processing`, or backend tasks cannot start. | Asynchronous task scheduling for document parsing, knowledge compilation, Embedding, and index building. | -| Task Executor | Executes backend tasks such as document parsing, OCR, Embedding, and index building. | Documents remain in `Parsing`, knowledge cannot be imported, or indexes cannot be built. | OCR, document parsing, Embedding, knowledge ingestion, index building, and other backend processing tasks. | +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. | + +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. ## View Service Details -On the **Service status** page, administrators can view the service `ID`, `Name`, `Service type`, `Host`, `Port`, and `Status`. When `Status` is `Alive`, the service is currently alive. +On the **Service status** page, administrators can view the service `Name`, `Service type`, `Host`, `Port`, and `Status`. -Administrators can open service details from **Actions**. Different services display different details. For example, the `mysql` service details show current database connection and process information, including `command`, `db`, `host`, `id`, `info`, `state`, `time`, and `user`. Administrators can use this information to determine whether there are long-running connections, waiting states, or abnormal queries. +Opening a service from **Actions** displays the status record returned by the Go Admin service. Depending on the entry, it can include the service name, type, host, port, status, elapsed health-check time, and an error or status message. Use the database or container administration tools provided by your deployment environment when you need database process lists or container operations. ![View Service Details](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/view_service_details_1.jpg) ![View Service Details](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/view_service_details_2.jpg) -Some services also provide an **Extra information** dialog that displays supplementary configuration information. For example, an object storage service may display information such as `store_type` and `user`. This information is mainly used to confirm service configuration. +The **Extra information** dialog displays the elapsed value and message included in the same status record. A failed dependency check can place its error text in the message field. ![View Service Details](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/view_service_details_3.jpg) ![View Service Details](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/view_service_details_4.jpg) -If a service's `Status` is not `Alive`, first record its `ID`, `Name`, `Service type`, `Host`, `Port`, and any abnormal information visible in the details dialog or **Extra information**. +If a service's status is not `alive`, record its name, service type, host, port, and message before troubleshooting the corresponding dependency or process. The Admin UI is mainly used to view service status. It does not provide direct troubleshooting entry points for containers, processes, networks, or logs. For further handling, check the corresponding deployment environment, including service runtime status, port connectivity, service logs, and related configurations. After identifying the cause, restart services, adjust configurations, or perform other recovery operations according to your operations process. diff --git a/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md b/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md index 2ab1394f57..55b4c30e56 100644 --- a/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md +++ b/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md @@ -14,7 +14,6 @@ The current page supports the following `Provider` options: | Provider | Description | | --- | --- | -| `Local` | Execute code directly in the current host process. | | `Self-Managed` | Use Daytona or Docker for localized deployment. | | `SSH` | Execute code on a remote machine through SSH. | | `AliyunCodeInterpreter` | Use Alibaba Cloud Function Compute Code Interpreter. | @@ -23,13 +22,10 @@ The current page supports the following `Provider` options: After selecting a `Provider`, the page displays the corresponding configuration area. -![Select Sandbox Provider](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/select_sandbox_provider.jpg) - -**Caution:** Sandbox configuration affects not only connection availability, but also code isolation, network access, file access, and runtime resource limits. In production environments, prefer `Self-Managed`, cloud, or independent remote execution solutions with isolation capabilities. Direct use of `Local` is not recommended. +**Caution:** Sandbox configuration affects not only connection availability, but also code isolation, network access, file access, and runtime resource limits. In production environments, use `Self-Managed`, cloud, or independent remote execution solutions with isolation capabilities. | Provider | Applicable scenario | Main characteristics | Recommendation | | --- | --- | --- | --- | -| `Local` | Local development and functional debugging | Runs code directly on the current host and is easy to configure. | Recommended only for controlled development and test environments. | | `Self-Managed` | Enterprise intranet and private deployment | Uses a self-managed sandbox service to execute code. Data and runtime environments can be controlled independently. | Suitable for production environments and scenarios with high data security requirements. | | `SSH` | Existing independent execution servers | Executes code on a remote host through SSH. | Suitable for reusing existing servers or custom runtime environments. | | `AliyunCodeInterpreter` | Alibaba Cloud-related services | Uses a cloud service to provide the code execution environment, making elastic scaling easier. | Suitable for organizations already using the corresponding cloud service. | @@ -40,28 +36,6 @@ After selecting a `Provider`, the page displays the corresponding configuration When configuring a sandbox, first fill in the connection information and runtime parameters required by the selected `Provider`, then use **Test connection** to verify availability. After the test succeeds, click **Save**. -## Local Runtime Configuration - -`Local configuration` configures the local code execution environment. The system uses the following configuration when executing code tasks such as Python and Node.js. - -1. Go to **Local Configuration**. -2. Configure each parameter according to the actual runtime environment. -3. Click **Test connection** to test whether the configuration is correct. -4. After the test succeeds, click **Save**. - -| Parameter | Description | Recommendation | -| --- | --- | --- | -| `Working Directory` | Working directory used during code execution, for temporary files generated during runtime. | Keep the default, or configure a local directory with read and write permissions. | -| `Python Binary` | Python executable name or path. | Usually `python3`. If using a virtual environment, enter the full Python path. | -| `Node.js Binary` | Node.js executable name or path. | Usually `node`. If installed elsewhere, enter the full path. | -| `Max Artifact Size (bytes)` | Maximum allowed size for a single generated file. | Configure according to business needs. The default usually satisfies common use. | -| `Max Artifacts` | Maximum number of files allowed in one run. | Keep the default to avoid generating too many temporary files. | -| `Max Memory (MB)` | Maximum memory available to a single code run. | Configure according to server resources. Increase it when resources are sufficient. | -| `Max Output (bytes)` | Maximum length of console output. | Keep the default to avoid oversized output. | -| `Timeout (seconds)` | Maximum runtime for a single code execution. | Set according to the business scenario. The task is terminated automatically after timeout. | - -If Python or Node.js is not installed, or the executable path is wrong, the connection test fails. - ## Self-Managed Configuration `Self-Managed` configuration connects to a deployed `SandboxExecutorManager` service for remote sandbox execution. If the code execution service is deployed on an independent server or in a container, complete this configuration. @@ -82,7 +56,7 @@ If Python or Node.js is not installed, or the executable path is wrong, the conn ## SSH Configuration -`SSH` configuration connects to a remote Linux host and executes Python, Node.js, and other code tasks on the remote server. After configuration, the system logs in to the specified server through SSH and executes code in the remote working directory. +`SSH` configuration connects to a remote Linux host and executes Python or Node.js code on the remote server. After configuration, the system logs in to the specified server through SSH and executes code in the remote working directory. 1. Go to **System management > Model service > SSH Configuration**. 2. Fill in the remote server connection information. @@ -120,7 +94,7 @@ The system supports `Password` and `PrivateKey` authentication. | `Max Output Bytes` | Maximum size of console output. | Keep the default. Output exceeding the limit is truncated. | | `Timeout (seconds)` | Maximum runtime for a single code execution. | The default is 30 seconds. Increase it when execution takes longer. | -Make sure the remote server has SSH enabled and allows the current user to log in. The configured user must have read and write permissions on the remote working directory and be able to execute Python, Node.js, and other runtime environments. When using private-key authentication, make sure the private key matches the server configuration. +Make sure the remote server has SSH enabled and allows the current user to log in. The configured user must have read and write permissions on the remote working directory and be able to execute the configured Python and Node.js binaries. When using private-key authentication, make sure the private key matches the server configuration. ## Alibaba Cloud CodeInterpreter Configuration diff --git a/docs/administrator/admin/ragflow_cli.md b/docs/administrator/admin/ragflow_cli.md index 7a7df76375..0800242521 100644 --- a/docs/administrator/admin/ragflow_cli.md +++ b/docs/administrator/admin/ragflow_cli.md @@ -9,590 +9,679 @@ sidebar_custom_props: { --- # RAGFlow CLI -The RAGFlow CLI is a command-line-based system administration tool that offers administrators an efficient and flexible method for system interaction and control. Operating on a client-server architecture, it communicates in real-time with the Admin Service, receiving administrator commands and dynamically returning execution results. +RAGFlow CLI is the Go command-line client for administering RAGFlow. In Admin mode it connects to the Go Admin Service, manages users and system settings, and shows the health of dependencies and registered RAGFlow processes. -## Using the RAGFlow CLI +## Install and start -1. Ensure the Admin Service is running. +For regular use, install the prebuilt Go CLI from the latest RAGFlow GitHub Release. The installer detects the operating system and CPU architecture, downloads the matching binary, verifies it against `SHA256SUMS`, and then installs it. -2. Install ragflow-cli. - - ```bash - pipx install ragflow-cli==0.27.2 - ``` - > You can also use `uv`, a tool for managing virtual environments and packages, to install RAGFlow CLI: `uv tool install ragflow-cli@0.27.2`. - -3. Launch the CLI client: - - ```bash - ragflow-cli -h 127.0.0.1 -p 9381 - ``` - - You will be prompted to enter the superuser's password to log in. - See [Default Administrative Account](#default-administrative-account) for how the initial password is chosen. - - **Parameters:** - - - -h: RAGFlow admin server host address - - - -p: RAGFlow admin server port - -## Default Administrative Account - -- Username: admin@ragflow.io -- Password: the value of the `ADMIN_DEFAULT_PASSWORD` (or `DEFAULT_SUPERUSER_PASSWORD`) environment variable; if neither is set when the admin server first starts, a random password is generated and written once to `logs/admin_bootstrap_password.txt` (mode 0600). Change it after the first login. - -## Supported Commands - -Commands are case-insensitive and must be terminated with a semicolon(;). - -### Service Manage Commands - -`LIST SERVICES;` - -- Lists all available services within the RAGFlow system. - -- [Example](#example-list-services) - -`SHOW SERVICE ;` - -- Shows detailed status information for the service identified by **id**. -- [Example](#example-show-service) - -`SHOW VERSION;` - -- Shows RAGFlow version. -- [Example](#example-show-version) - -### User Management Commands - -`LIST USERS;` - -- Lists all users known to the system. -- [Example](#example-list-users) - -`SHOW USER ;` - -- Shows details and permissions for the user specified by **email**. The username must be enclosed in single or double quotes. -- [Example](#example-show-user) - -`CREATE USER ;` - -- Create user by username and password. The username and password must be enclosed in single or double quotes. -- [Example](#example-create-user) - -`DROP USER ;` - -- Removes the specified user from the system. Use with caution. -- [Example](#example-drop-user) - -`ALTER USER PASSWORD ;` - -- Changes the password for the specified user. -- [Example](#example-alter-user-password) - -`ALTER USER ACTIVE ;` - -- Changes the user to active or inactive. -- [Example](#example-alter-user-active) - -`GENERATE KEY FOR USER ;` - -- Generates a new API key for the specified user. -- [Example](#example-generate-key) - -`LIST KEYS OF ;` - -- Lists all API keys associated with the specified user. -- [Example](#example-list-keys) - -`DROP KEY OF ;` - -- Deletes a specific API key for the specified user. -- [Example](#example-drop-key) - -### Data and Agent Commands - -`LIST DATASETS OF ;` - -- Lists the datasets associated with the specified user. -- [Example](#example-list-datasets-of-user) - -`LIST AGENTS OF ;` - -- Lists the agents associated with the specified user. -- [Example](#example-list-agents-of-user) - -### System Info - -`SHOW VERSION;` -- Display the current RAGFlow version. -- [Example](#example-show-version) - -`GRANT ADMIN ` -- Grant administrator privileges to the specified user. -- [Example](#example-grant-admin) - -`REVOKE ADMIN ` -- Revoke administrator privileges from the specified user. -- [Example](#example-revoke-admin) - -`LIST VARS` -- List all system settings. -- [Example](#example-list-vars) - -`SHOW VAR ` -- Display the content of a specific system configuration/setting by its name or name prefix. -- [Example](#example-show-var) - -`SET VAR ` -- Set the value for a specified configuration item. -- [Example](#example-set-var) - -`LIST CONFIGS` -- List all system configurations. -- [Example](#example-list-configs) - -`LIST ENVS` -- List all system environments which can accessed by Admin service. -- [Example](#example-list-environments) - -### Meta-Commands - -- \? or \help - Shows help information for the available commands. -- \q or \quit - Exits the CLI application. -- [Example](#example-meta-commands) - -### Examples - - - -- List all available services. - -``` -ragflow> list services; -command: list services; -Listing all services -+-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+---------+ -| extra | host | id | name | port | service_type | status | -+-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+---------+ -| {} | 0.0.0.0 | 0 | ragflow_0 | 9380 | ragflow_server | Timeout | -| {'meta_type': 'mysql', 'password': 'infini_rag_flow', 'username': 'root'} | localhost | 1 | mysql | 5455 | meta_data | Alive | -| {'password': 'infini_rag_flow', 'store_type': 'minio', 'user': 'rag_flow'} | localhost | 2 | minio | 9000 | file_store | Alive | -| {'password': 'infini_rag_flow', 'retrieval_type': 'elasticsearch', 'username': 'elastic'} | localhost | 3 | elasticsearch | 1200 | retrieval | Alive | -| {'db_name': 'default_db', 'retrieval_type': 'infinity'} | localhost | 4 | infinity | 23817 | retrieval | Timeout | -| {'database': 1, 'mq_type': 'redis', 'password': 'infini_rag_flow'} | localhost | 5 | redis | 6379 | message_queue | Alive | -+-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+---------+ +Default installation on Linux and macOS: +```bash +curl -fsSL https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.sh | sh ``` - +When `VERSION` is omitted, the installer resolves the latest GitHub Release and installs the CLI that matches the current operating system and CPU architecture. To install a specific version, pass `VERSION` to the installer: -- Show ragflow_server. - -``` -ragflow> show service 0; -command: show service 0; -Showing service: 0 -Service ragflow_0 is alive. Detail: -Confirm elapsed: 26.0 ms. +```bash +curl -fsSL https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.sh \ + | VERSION=v0.27.2 sh ``` -- Show mysql. +Both forms are supported. Pin a version for production or reproducible installations so that a later Release does not change the installed version. -``` -ragflow> show service 1; -command: show service 1; -Showing service: 1 -Service mysql is alive. Detail: -+---------+----------+------------------+------+------------------+------------------------+-------+-----------------+ -| command | db | host | id | info | state | time | user | -+---------+----------+------------------+------+------------------+------------------------+-------+-----------------+ -| Daemon | None | localhost | 5 | None | Waiting on empty queue | 16111 | event_scheduler | -| Sleep | rag_flow | 172.18.0.1:40046 | 1610 | None | | 2 | root | -| Query | rag_flow | 172.18.0.1:35882 | 1629 | SHOW PROCESSLIST | init | 0 | root | -+---------+----------+------------------+------+------------------+------------------------+-------+-----------------+ +The default installation path is `/usr/local/bin/ragflow-cli`. If the current user cannot write to that directory, the installer requests `sudo` permission. To install into a user-writable directory instead, set `INSTALL_DIR` and ensure that directory is on `PATH`: + +```bash +curl -fsSL https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.sh | INSTALL_DIR="$HOME/.local/bin" sh ``` -- Show minio. +Default installation on Windows PowerShell: -``` -ragflow> show service 2; -command: show service 2; -Showing service: 2 -Service minio is alive. Detail: -Confirm elapsed: 2.1 ms. +```powershell +irm https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.ps1 | iex ``` -- Show elasticsearch. +When no version is specified, the Windows installer also uses the latest GitHub Release. To install a specific version, download the script and pass `-Version`: -``` -ragflow> show service 3; -command: show service 3; -Showing service: 3 -Service elasticsearch is alive. Detail: -+----------------+------+--------------+---------+----------------+--------------+---------------+--------------+------------------------------+----------------------------+-----------------+-------+---------------+---------+-------------+---------------------+--------+------------+--------------------+ -| cluster_name | docs | docs_deleted | indices | indices_shards | jvm_heap_max | jvm_heap_used | jvm_versions | mappings_deduplicated_fields | mappings_deduplicated_size | mappings_fields | nodes | nodes_version | os_mem | os_mem_used | os_mem_used_percent | status | store_size | total_dataset_size | -+----------------+------+--------------+---------+----------------+--------------+---------------+--------------+------------------------------+----------------------------+-----------------+-------+---------------+---------+-------------+---------------------+--------+------------+--------------------+ -| docker-cluster | 717 | 86 | 37 | 42 | 3.76 GB | 1.74 GB | 21.0.1+12-29 | 6575 | 48.0 KB | 8521 | 1 | ['8.11.3'] | 7.52 GB | 4.55 GB | 61 | green | 4.60 MB | 4.60 MB | -+----------------+------+--------------+---------+----------------+--------------+---------------+--------------+------------------------------+----------------------------+-----------------+-------+---------------+---------+-------------+---------------------+--------+------------+--------------------+ +```powershell +irm https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.ps1 -OutFile install.ps1 +./install.ps1 -Version v0.27.2 ``` -- Show infinity. +The Windows installer installs `ragflow-cli.exe` under `%LOCALAPPDATA%\Programs\RAGFlow` by default and adds that directory to the user `PATH`. Restart the terminal if the installer reports that `PATH` was updated. -``` -ragflow> show service 4; -command: show service 4; -Showing service: 4 -Fail to show service, code: 500, message: Infinity is not in use. +Verify the installation: + +```bash +ragflow-cli --version ``` -- Show redis. +The installation scripts are maintained in [`tools/scripts/install.sh`](https://github.com/infiniflow/ragflow/blob/main/tools/scripts/install.sh) and [`tools/scripts/install.ps1`](https://github.com/infiniflow/ragflow/blob/main/tools/scripts/install.ps1). -``` -ragflow> show service 5; -command: show service 5; -Showing service: 5 -Service redis is alive. Detail: -+-----------------+-------------------+---------------------------+-------------------------+---------------+-------------+--------------------------+---------------------+-------------+ -| blocked_clients | connected_clients | instantaneous_ops_per_sec | mem_fragmentation_ratio | redis_version | server_mode | total_commands_processed | total_system_memory | used_memory | -+-----------------+-------------------+---------------------------+-------------------------+---------------+-------------+--------------------------+---------------------+-------------+ -| 0 | 2 | 1 | 10.41 | 7.2.4 | standalone | 10446 | 30.84G | 1.10M | -+-----------------+-------------------+---------------------------+-------------------------+---------------+-------------+--------------------------+---------------------+-------------+ -``` - +If you are developing or modifying the CLI, build the Go server and CLI binaries from the repository root instead: -- Show RAGFlow version - -``` -ragflow> show version; -+-----------------------+ -| version | -+-----------------------+ -| v0.21.0-241-gc6cf58d5 | -+-----------------------+ +```bash +bash build.sh --all ``` - +Use `--all` for the initial build from a fresh checkout. After the native libraries and C++ bindings are available, use `bash build.sh --go` for subsequent Go-only rebuilds. -- List all user. +Before starting Admin, start the required dependencies and complete the standalone database migration as described in [Start supporting services](../../develop/launch_ragflow_from_source.md#2-start-supporting-services) and [Migrate and launch the Go backend](../../develop/launch_ragflow_from_source.md#3-migrate-and-launch-the-go-backend). The CLI does not start or migrate the server for you. -``` -ragflow> list users; -command: list users; -Listing all users -+-------------------------------+----------------------+-----------+----------+ -| create_date | email | is_active | nickname | -+-------------------------------+----------------------+-----------+----------+ -| Mon, 22 Sep 2025 10:59:04 GMT | admin@ragflow.io | 1 | admin | -| Sun, 14 Sep 2025 17:36:27 GMT | lynn_inf@hotmail.com | 1 | Lynn | -+-------------------------------+----------------------+-----------+----------+ +For a source-development checkout, start the Admin Service with `RAGFLOW_DEV_MODE=true` to bypass the code and database version downgrade check. This setting does not run database migrations or change the schema. Do not set it in production. Start Admin before the API server, ingestors, and syncers: + +```bash +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin --init-superuser ``` - +If this creates the first superuser, its email is `admin@ragflow.io` and its initial password is `admin`. Change that password immediately after the first login. The option does not reset an existing superuser's password. -- Show specified user. +Then start the CLI in Admin mode. It connects to `127.0.0.1:9381` by default: -``` -ragflow> show user "admin@ragflow.io"; -command: show user "admin@ragflow.io"; -Showing user: admin@ragflow.io -+-------------------------------+------------------+-----------+--------------+------------------+--------------+----------+-----------------+---------------+--------+-------------------------------+ -| create_date | email | is_active | is_anonymous | is_authenticated | is_superuser | language | last_login_time | login_channel | status | update_date | -+-------------------------------+------------------+-----------+--------------+------------------+--------------+----------+-----------------+---------------+--------+-------------------------------+ -| Mon, 22 Sep 2025 10:59:04 GMT | admin@ragflow.io | 1 | 0 | 1 | True | Chinese | None | None | 1 | Mon, 22 Sep 2025 10:59:04 GMT | -+-------------------------------+------------------+-----------+--------------+------------------+--------------+----------+-----------------+---------------+--------+-------------------------------+ +```bash +ragflow-cli --admin ``` - +When using a binary built from source, replace `ragflow-cli` with `./bin/ragflow-cli` in the following examples. -- Create new user. +To connect to another Admin Service, pass a `host:port` value: -``` -ragflow> create user "example@ragflow.io" "psw"; -command: create user "example@ragflow.io" "psw"; -Create user: example@ragflow.io, password: psw, role: user -+----------------------------------+--------------------+----------------------------------+--------------+---------------+----------+ -| access_token | email | id | is_superuser | login_channel | nickname | -+----------------------------------+--------------------+----------------------------------+--------------+---------------+----------+ -| 5cdc6d1e9df111f099b543aee592c6bf | example@ragflow.io | 5cdc6ca69df111f099b543aee592c6bf | False | password | | -+----------------------------------+--------------------+----------------------------------+--------------+---------------+----------+ +```bash +ragflow-cli --admin --host 192.0.2.10:9381 ``` - +To log in when starting the CLI, provide the administrator email address and enter the password at the prompt: -- Alter user password. - -``` -ragflow> alter user password "example@ragflow.io" "newpsw"; -command: alter user password "example@ragflow.io" "newpsw"; -Alter user: example@ragflow.io, password: newpsw -Password updated successfully! +```bash +ragflow-cli --admin \ + --host 127.0.0.1:9381 \ + --user admin@ragflow.io ``` - +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' '';`. -- Alter user active, turn off. +| Option | Description | +| --- | --- | +| `--admin`, `-admin` | Start in Admin mode. | +| `-h`, `--host ` | Admin Service address. The default is `127.0.0.1:9381`. | +| `-u`, `--user ` | Administrator email address. | +| `-p`, `--password ` | Administrator password. Prefer the interactive prompt to avoid exposing it in command-line arguments. | +| `-k`, `--key ` | Key file used by the client. | +| `-o`, `--output ` | Output format: `table`, `plain`, or `json`. | +| `-v`, `--verbose` | Enable verbose output. | -``` -ragflow> alter user active "example@ragflow.io" off; -command: alter user active "example@ragflow.io" off; -Alter user example@ragflow.io activate status, turn off. -Turn off user activate status successfully! +## Commands + +### Syntax conventions + +- `` is required and must be replaced with an actual value. +- `[OPTION '']` is optional. Omit the entire segment when it is not needed. +- Command keywords are case-insensitive and are shown in uppercase. +- Keep the quotation marks around string values. +- End SQL-like commands with a semicolon (`;`). +- `RAGFlow(admin)>` is the interactive prompt. Enter only the command after the prompt. +- Commands that access protected Admin resources require an authenticated administrator session. `LOGIN ADMIN`, `PING`, `SHOW VERSION`, `SHOW CURRENT`, `SHOW ADMIN SERVER`, `LIST API SERVER`, `SHOW API SERVER`, and meta-commands do not require an existing login. + +### 1. Session and server commands + +#### 1.1 LOGIN ADMIN + +Logs in to the Admin Service with an administrator account. If `PASSWORD` is omitted, the CLI prompts for the password. + +**Syntax** + +```sql +LOGIN ADMIN '' [PASSWORD '']; ``` - +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | Administrator email address. | +| `[PASSWORD '']` | No | Administrator password. Omit this segment to enter the password interactively. | -- Drop user. +**Example** -``` -ragflow> Drop user "example@ragflow.io"; -command: Drop user "example@ragflow.io"; -Drop user: example@ragflow.io -Successfully deleted user. Details: -Start to delete owned tenant. -- Deleted 2 tenant-LLM records. -- Deleted 0 langfuse records. -- Deleted 1 tenant. -- Deleted 1 user-tenant records. -- Deleted 1 user. -Delete done! +```text +RAGFlow(admin)> LOGIN ADMIN 'admin@ragflow.io' PASSWORD ''; ``` -Delete user's data at the same time. +#### 1.2 LOGOUT - +Logs out of the current Admin session and clears the login token. -- Generate API key for user. +**Syntax** -``` -admin> generate key for user "example@ragflow.io"; -Generating API key for user: example@ragflow.io -+----------------------------------+-------------------------------+---------------+----------------------------------+-----------------------------------------------------+-------------+-------------+ -| beta | create_date | create_time | tenant_id | token | update_date | update_time | -+----------------------------------+-------------------------------+---------------+----------------------------------+-----------------------------------------------------+-------------+-------------+ -| Es9OpZ6hrnPGeYA3VU1xKUkj6NCb7cp- | Mon, 12 Jan 2026 15:19:11 GMT | 1768227551361 | 5d5ea8a3efc111f0a79b80fa5b90e659 | ragflow-piwVJHEk09M5UN3LS_Xx9HA7yehs3yNOc9GGsD4jzus | None | None | -+----------------------------------+-------------------------------+---------------+----------------------------------+-----------------------------------------------------+-------------+-------------+ +```sql +LOGOUT; ``` - +**Example** -- List all API keys for user. - -``` -admin> list keys of "example@ragflow.io"; -Listing API keys for user: example@ragflow.io -+----------------------------------+-------------------------------+---------------+-----------+--------+----------------------------------+-----------------------------------------------------+-------------------------------+---------------+ -| beta | create_date | create_time | dialog_id | source | tenant_id | token | update_date | update_time | -+----------------------------------+-------------------------------+---------------+-----------+--------+----------------------------------+-----------------------------------------------------+-------------------------------+---------------+ -| Es9OpZ6hrnPGeYA3VU1xKUkj6NCb7cp- | Mon, 12 Jan 2026 15:19:11 GMT | 1768227551361 | None | None | 5d5ea8a3efc111f0a79b80fa5b90e659 | ragflow-piwVJHEk09M5UN3LS_Xx9HA7yehs3yNOc9GGsD4jzus | Mon, 12 Jan 2026 15:19:11 GMT | 1768227551361 | -+----------------------------------+-------------------------------+---------------+-----------+--------+----------------------------------+-----------------------------------------------------+-------------------------------+---------------+ +```text +RAGFlow(admin)> LOGOUT; +SUCCESS ``` - +#### 1.3 PING -- Drop API key for user. +Checks whether the Admin Service is reachable. -``` -admin> drop key "ragflow-piwVJHEk09M5UN3LS_Xx9HA7yehs3yNOc9GGsD4jzus" of "example@ragflow.io"; -Dropping API key for user: example@ragflow.io -API key deleted successfully +**Syntax** + +```sql +PING; ``` - +**Example** -- List the specified user's dataset. - -``` -ragflow> list datasets of "lynn_inf@hotmail.com"; -command: list datasets of "lynn_inf@hotmail.com"; -Listing all datasets of user: lynn_inf@hotmail.com -+-----------+-------------------------------+---------+----------+---------------+------------+--------+-----------+-------------------------------+ -| chunk_num | create_date | doc_num | language | name | permission | status | token_num | update_date | -+-----------+-------------------------------+---------+----------+---------------+------------+--------+-----------+-------------------------------+ -| 29 | Mon, 15 Sep 2025 11:56:59 GMT | 12 | Chinese | test_dataset | me | 1 | 12896 | Fri, 19 Sep 2025 17:50:58 GMT | -| 4 | Sun, 28 Sep 2025 11:49:31 GMT | 6 | Chinese | dataset_share | team | 1 | 1121 | Sun, 28 Sep 2025 14:41:03 GMT | -+-----------+-------------------------------+---------+----------+---------------+------------+--------+-----------+-------------------------------+ +```text +RAGFlow(admin)> PING; +SUCCESS ``` - +#### 1.4 SHOW VERSION -- List the specified user's agents. +Shows the RAGFlow version and edition reported by the Admin Service. -``` -ragflow> list agents of "lynn_inf@hotmail.com"; -command: list agents of "lynn_inf@hotmail.com"; -Listing all agents of user: lynn_inf@hotmail.com -+-----------------+-------------+------------+-----------------+ -| canvas_category | canvas_type | permission | title | -+-----------------+-------------+------------+-----------------+ -| agent | None | team | research_helper | -+-----------------+-------------+------------+-----------------+ +**Syntax** + +```sql +SHOW VERSION; ``` - +**Example** -- Display the current RAGFlow version. - -``` -ragflow> show version; -show_version -+-----------------------+ -| version | -+-----------------------+ -| v0.25.4-24-g6f60e9f9e | -+-----------------------+ +```text +RAGFlow(admin)> SHOW VERSION; ``` - +#### 1.5 SHOW CURRENT -- Grant administrator privileges to the specified user. +Shows the current CLI mode, server connection, authentication state, and output format. -``` -ragflow> grant admin "anakin.skywalker@ragflow.io"; -Grant successfully! +**Syntax** + +```sql +SHOW CURRENT; ``` - +**Example** -- Revoke administrator privileges from the specified user. - -``` -ragflow> revoke admin "anakin.skywalker@ragflow.io"; -Revoke successfully! +```text +RAGFlow(admin)> SHOW CURRENT; ``` - +#### 1.6 SHOW ADMIN SERVER -- List all system settings. +Shows the Admin Service connection stored by the CLI. -``` -ragflow> list vars; -+-----------+---------------------+--------------+-----------+ -| data_type | name | setting_type | value | -+-----------+---------------------+--------------+-----------+ -| string | default_role | config | user | -| bool | enable_whitelist | config | true | -| string | mail.default_sender | config | | -| string | mail.password | config | | -| integer | mail.port | config | 15 | -| string | mail.server | config | localhost | -| integer | mail.timeout | config | 10 | -| bool | mail.use_ssl | config | true | -| bool | mail.use_tls | config | false | -| string | mail.username | config | | -+-----------+---------------------+--------------+-----------+ +**Syntax** + +```sql +SHOW ADMIN SERVER; ``` - +**Example** -- Display the content of a specific system configuration/setting by its name or name prefix. - -``` -ragflow> show var mail.server; -+-----------+-------------+--------------+-----------+ -| data_type | name | setting_type | value | -+-----------+-------------+--------------+-----------+ -| string | mail.server | config | localhost | -+-----------+-------------+--------------+-----------+ +```text +RAGFlow(admin)> SHOW ADMIN SERVER; ``` - +### 2. Service commands -- Set the value for a specified configuration item. +The Admin Service combines dependency health checks with heartbeat registrations from Go API servers, ingestors, and file syncers. The runtime service types are `api_server`, `ingestor`, and `file_syncer`. The former `task_executor` service type is not used. -``` -ragflow> set var mail.server 127.0.0.1; -Set variable successfully +#### 2.1 LIST SERVICES + +Lists infrastructure dependencies and runtime services registered through heartbeats. + +**Syntax** + +```sql +LIST SERVICES; ``` +**Example** - - -- List all system configurations. - -``` -ragflow> list configs; -+-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+ -| extra | host | id | name | port | service_type | -+-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+ -| {} | 0.0.0.0 | 0 | ragflow_0 | 9380 | ragflow_server | -| {'meta_type': 'mysql', 'password': 'infini_rag_flow', 'username': 'root'} | localhost | 1 | mysql | 5455 | meta_data | -| {'password': 'infini_rag_flow', 'store_type': 'minio', 'user': 'rag_flow'} | localhost | 2 | minio | 9000 | file_store | -| {'password': 'infini_rag_flow', 'retrieval_type': 'elasticsearch', 'username': 'elastic'} | localhost | 3 | elasticsearch | 1200 | retrieval | -| {'db_name': 'default_db', 'retrieval_type': 'infinity'} | localhost | 4 | infinity | 23817 | retrieval | -| {'database': 1, 'mq_type': 'redis', 'password': 'infini_rag_flow'} | localhost | 5 | redis | 6379 | message_queue | -| {'message_queue_type': 'redis'} | | 6 | task_executor | 0 | task_executor | -+-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+ +```text +RAGFlow(admin)> LIST SERVICES; ``` - +The result can include MySQL, Elasticsearch, MinIO, the Kvrocks cache, the NATS message queue, Go API servers, ingestors, and file syncers. -- List all system environments which can accessed by Admin service. +#### 2.2 SHOW SERVICE -``` -ragflow> list envs; -+-------------------------+------------------+ -| env | value | -+-------------------------+------------------+ -| DOC_ENGINE | elasticsearch | -| DEFAULT_SUPERUSER_EMAIL | admin@ragflow.io | -| DB_TYPE | mysql | -| DEVICE | cpu | -| STORAGE_IMPL | MINIO | -+-------------------------+------------------+ +Shows the current status of one service. Use the service name returned by `LIST SERVICES`, not a numeric ID. + +**Syntax** + +```sql +SHOW SERVICE ''; ``` +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | Service name returned by `LIST SERVICES`, such as `mysql`. | - +**Example** -- Show help information. - -``` -ragflow> \help -command: \help - -Commands: -LIST SERVICES -SHOW SERVICE -STARTUP SERVICE -SHUTDOWN SERVICE -RESTART SERVICE -LIST USERS -SHOW USER -DROP USER -CREATE USER -ALTER USER PASSWORD -ALTER USER ACTIVE -LIST DATASETS OF -LIST AGENTS OF -CREATE ROLE -DROP ROLE -ALTER ROLE SET DESCRIPTION -LIST ROLES -SHOW ROLE -GRANT ON TO ROLE -REVOKE ON TO ROLE -ALTER USER SET ROLE -SHOW USER PERMISSION -SHOW VERSION -GRANT ADMIN -REVOKE ADMIN -GENERATE KEY FOR USER -LIST KEYS OF -DROP KEY OF - -Meta Commands: - \?, \h, \help Show this help - \q, \quit, \exit Quit the CLI +```text +RAGFlow(admin)> SHOW SERVICE 'mysql'; ``` -- Exit +### 3. User commands +#### 3.1 LIST USERS + +Lists RAGFlow users. + +**Syntax** + +```sql +LIST USERS; ``` -ragflow> \q -command: \q + +**Example** + +```text +RAGFlow(admin)> LIST USERS; +``` + +#### 3.2 SHOW USER + +Shows details for one user. + +**Syntax** + +```sql +SHOW USER ''; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | User email address. | + +**Example** + +```text +RAGFlow(admin)> SHOW USER 'alice@example.com'; +``` + +#### 3.3 CREATE USER + +Creates a user with the standard `user` role. + +**Syntax** + +```sql +CREATE USER '' ''; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | Email address for the new user. | +| `` | Yes | Initial password for the new user. | + +**Example** + +```text +RAGFlow(admin)> CREATE USER 'alice@example.com' 'Alice@123456'; +SUCCESS +``` + +#### 3.4 ALTER USER ACTIVE + +Activates or deactivates a user. + +**Syntax** + +```sql +ALTER USER ACTIVE '' ; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | User email address. | +| `` | Yes | `on` activates the user; `off` deactivates the user. | + +**Example** + +```text +RAGFlow(admin)> ALTER USER ACTIVE 'alice@example.com' off; +SUCCESS +``` + +#### 3.5 ALTER USER PASSWORD + +Changes a user's password. + +**Syntax** + +```sql +ALTER USER PASSWORD '' ''; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | User email address. | +| `` | Yes | New password. | + +**Example** + +```text +RAGFlow(admin)> ALTER USER PASSWORD 'alice@example.com' 'NewPassword@123'; +SUCCESS +``` + +#### 3.6 DROP USER + +Deletes a user and associated data. + +An active user cannot be deleted. Run `ALTER USER ACTIVE '' off;` before `DROP USER`. Otherwise, the Admin Service returns `user is active and can't be deleted. Please deactivate the user first`. + +**Syntax** + +```sql +DROP USER ''; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | Email address of a deactivated user. | + +**Example** + +```text +RAGFlow(admin)> ALTER USER ACTIVE 'alice@example.com' off; +SUCCESS +RAGFlow(admin)> DROP USER 'alice@example.com'; +SUCCESS +``` + +### 4. Configuration commands + +#### 4.1 SHOW VAR + +Shows a runtime setting by its exact name or name prefix. + +**Syntax** + +```sql +SHOW VAR ''; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | Setting name or prefix, such as `mail.timeout`. | + +**Example** + +```text +RAGFlow(admin)> SHOW VAR 'mail.timeout'; +``` + +#### 4.2 LIST VARS + +Lists runtime settings. + +**Syntax** + +```sql +LIST VARS; +``` + +**Example** + +```text +RAGFlow(admin)> LIST VARS; +``` + +#### 4.3 LIST CONFIGS + +Lists the effective Admin Service configuration. This command does not list service health; use `LIST SERVICES` for that purpose. + +**Syntax** + +```sql +LIST CONFIGS; +``` + +**Example** + +```text +RAGFlow(admin)> LIST CONFIGS; +``` + +#### 4.4 LIST ENVS + +Lists the environment summary visible to the Admin Service. + +**Syntax** + +```sql +LIST ENVS; +``` + +**Example** + +```text +RAGFlow(admin)> LIST ENVS; +``` + +### 5. Ingestion commands + +#### 5.1 LIST INGESTORS + +Lists ingestors that have registered with the Admin Service through heartbeats. + +**Syntax** + +```sql +LIST INGESTORS; +``` + +**Example** + +```text +RAGFlow(admin)> LIST INGESTORS; +``` + +#### 5.2 LIST INGESTION TASKS + +Lists ingestion tasks known to the Admin Service. + +**Syntax** + +```sql +LIST INGESTION TASKS; +``` + +**Example** + +```text +RAGFlow(admin)> LIST INGESTION TASKS; +``` + +### 6. API server commands + +`LIST API SERVER` and `SHOW API SERVER` inspect API server connections saved in the CLI configuration. They do not query the Admin Service heartbeat registry. To find running Go API servers registered by heartbeat, use `LIST SERVICES` and look for `type=api_server`. + +#### 6.1 LIST API SERVER + +Lists API server connections saved in the local CLI configuration. + +**Syntax** + +```sql +LIST API SERVER; +``` + +**Example** + +```text +RAGFlow(admin)> LIST API SERVER; +``` + +An empty local configuration produces `No data to print` even when a Go API server is running and registered with the Admin Service. + +#### 6.2 SHOW API SERVER + +Shows one API server connection from the local CLI configuration. + +**Syntax** + +```sql +SHOW API SERVER ''; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | Local API server configuration name, such as `default`. | + +**Example** + +```text +RAGFlow(admin)> SHOW API SERVER 'default'; +``` + +If the name does not exist in the local configuration, the command returns `api_server=N/A`. + +### 7. Message queue commands + +The MQ commands operate on the NATS JetStream task stream used by ingestors. When an ingestor is running, it can consume a published test message before a subsequent `MQ LIST` or `MQ PULL` command observes it. + +#### 7.1 MQ SHOW + +Shows message queue statistics, including consumer, message, pending, waiting, and acknowledgement counts. + +**Syntax** + +```sql +MQ SHOW; +``` + +**Example** + +```text +RAGFlow(admin)> MQ SHOW; +``` + +#### 7.2 MQ LIST + +Lists messages currently retained in the task stream. The optional `PENDING` keyword is accepted by the CLI. + +**Syntax** + +```sql +MQ LIST [PENDING]; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `[PENDING]` | No | Requests the pending-message form of the command. | + +**Example** + +```text +RAGFlow(admin)> MQ LIST; +``` + +#### 7.3 MQ PUBLISH + +Publishes a test message to the ingestion task subject. + +**Syntax** + +```sql +MQ PUBLISH ''; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `` | Yes | String stored as the test task identifier. | + +**Example** + +```text +RAGFlow(admin)> MQ PUBLISH 'manual-ingestion-test'; +SUCCESS +``` + +A successful response confirms that NATS JetStream accepted the message. If an ingestor is waiting for work, it can consume and acknowledge the message immediately. + +#### 7.4 MQ PULL + +Manually pulls messages from the ingestion task consumer. The default count is `1`. By default, pulled messages are acknowledged; `NOACK` negatively acknowledges them so that they can be redelivered. + +**Syntax** + +```sql +MQ PULL [] [NOACK]; +``` + +| Parameter | Required | Description | +| --- | --- | --- | +| `[]` | 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** + +```text +RAGFlow(admin)> MQ PULL 1 NOACK; +``` + +### 8. Meta-commands + +#### 8.1 HELP + +Shows CLI help. + +**Syntax** + +```text +\? +\h +\help +``` + +**Example** + +```text +RAGFlow(admin)> \help +``` + +#### 8.2 PWD + +Shows the current working directory. + +**Syntax** + +```text +\pwd +``` + +**Example** + +```text +RAGFlow(admin)> \pwd +``` + +#### 8.3 QUIT + +Exits the CLI. + +**Syntax** + +```text +\q +\quit +\exit +``` + +**Example** + +```text +RAGFlow(admin)> \q Goodbye! ``` diff --git a/docs/administrator/configurations/config_ssl_cert.md b/docs/administrator/configurations/config_ssl_cert.md index 707381e07e..c461633803 100644 --- a/docs/administrator/configurations/config_ssl_cert.md +++ b/docs/administrator/configurations/config_ssl_cert.md @@ -94,12 +94,11 @@ If the changes do not take effect, exit the container and restart it: ```bash exit -docker restart docker-ragflow-cpu-1 +docker compose --env-file docker/.env -f docker/docker-compose.yml restart ragflow-cpu ``` ## Configuration Persistence :::tip IMPORTANT -Changes made via `docker cp` and `docker exec` are lost if the container is removed or stopped via `docker-compose down`. -**Recommendation**: After a successful test, store the certificates on the host machine and use `volumes` in your `docker-compose.yaml` to mount the certificates and `ragflow.conf` permanently. +Changes made with `docker cp` or `docker exec` are lost when the RAGFlow container is recreated. After a successful test, store the certificates on the host and add persistent certificate and `ragflow.conf` volume mounts to the `ragflow-cpu` service in `docker/docker-compose.yml`. ::: diff --git a/docs/administrator/configurations/configurations.md b/docs/administrator/configurations/configurations.md index ec8a77eb6e..c7df90050c 100644 --- a/docs/administrator/configurations/configurations.md +++ b/docs/administrator/configurations/configurations.md @@ -7,24 +7,24 @@ sidebar_custom_props: { --- # Configuration -Configurations for deploying RAGFlow via Docker. +Configuration reference for deploying the Go implementation of RAGFlow with Docker Compose. ## Guidelines -When it comes to system configurations, you will need to manage the following files: +The Go Docker deployment uses the following files: -- [.env](https://github.com/infiniflow/ragflow/blob/main/docker/.env): Contains important environment variables for Docker. -- [service_conf.yaml.template](https://github.com/infiniflow/ragflow/blob/main/docker/service_conf.yaml.template): Configures the back-end services. It specifies the system-level configuration for RAGFlow and is used by its API server and task executor. Upon container startup, the `service_conf.yaml` file will be generated based on this template file. This process replaces any environment variables within the template, allowing for dynamic configuration tailored to the container's environment. -- [docker-compose.yml](https://github.com/infiniflow/ragflow/blob/main/docker/docker-compose.yml): The Docker Compose file for starting up the RAGFlow service. +- [.env](https://github.com/infiniflow/ragflow/blob/main/docker/.env): Defines the Docker image, service profiles, published ports, credentials, and other deployment environment variables. +- [service_conf.yaml.template](https://github.com/infiniflow/ragflow/blob/main/docker/service_conf.yaml.template): Defines the configuration consumed by the Go services. The container generates `service_conf.yaml` from this template and substitutes its environment variables during startup. +- [docker-compose.yml](https://github.com/infiniflow/ragflow/blob/main/docker/docker-compose.yml): Starts the Go RAGFlow service together with the dependencies selected through Compose profiles. +- [docker-compose-base.yml](https://github.com/infiniflow/ragflow/blob/main/docker/docker-compose-base.yml): Defines shared dependencies such as the document engine, metadata database, MinIO, Kvrocks, NATS, and ClickHouse. -To update the default HTTP serving port (80), go to [docker-compose.yml](https://github.com/infiniflow/ragflow/blob/main/docker/docker-compose.yml) and change `80:80` -to `:80`. +To change the public HTTP or HTTPS port, update `SVR_WEB_HTTP_PORT` or `SVR_WEB_HTTPS_PORT` in **docker/.env**. Their defaults are `80` and `443`. :::tip NOTE Updates to the above configurations require a reboot of all containers to take effect: ```bash -docker compose -f docker/docker-compose.yml up -d +docker compose --env-file docker/.env -f docker/docker-compose.yml up -d ``` ::: @@ -32,24 +32,27 @@ docker compose -f docker/docker-compose.yml up -d ## Docker Compose - **docker-compose.yml** - Sets up environment for RAGFlow and its dependencies. + Starts the Go RAGFlow service and selects the required dependency profiles. - **docker-compose-base.yml** - Sets up environment for RAGFlow's dependencies: Elasticsearch/[Infinity](https://github.com/infiniflow/infinity), MySQL, MinIO, and Redis. - -:::danger IMPORTANT -We do not actively maintain **docker-compose-CN-oc9.yml**, **docker-compose-macos.yml**, so use them at your own risk. However, you are welcome to file a pull request to improve them. -::: + Defines the shared dependency services used by the selected document engine, metadata database, object storage, cache, queue, and analytical storage. ## Docker Environment Variables -The [.env](https://github.com/infiniflow/ragflow/blob/main/docker/.env) file contains important environment variables for Docker. +The [.env](https://github.com/infiniflow/ragflow/blob/main/docker/.env) file contains the environment variables for the Go Docker deployment. + +### Metadata Database + +- `DB_TYPE` + The business metadata database type. Defaults to `mysql`. Set it to `oceanbase` when connecting to OceanBase through its MySQL-compatible protocol. +- `METADATA_DB_PROFILE` + The Compose profile for the metadata database. Defaults to `mysql`. ### Elasticsearch - `STACK_VERSION` - The version of Elasticsearch. Defaults to `8.11.3` + The version of Elasticsearch. Defaults to `8.11.3`. - `ES_PORT` - The port used to expose the Elasticsearch service to the host machine, allowing **external** access to the service running inside the Docker container. Defaults to `1200`. + The port used to expose the Elasticsearch service to the host machine, allowing **external** access to the service running inside the Docker container. Defaults to `1200`. - `ELASTIC_PASSWORD` The password for Elasticsearch. @@ -61,7 +64,7 @@ The [.env](https://github.com/infiniflow/ragflow/blob/main/docker/.env) file con ### Resource Management - `MEM_LIMIT` - The maximum amount of the memory, in bytes, that *a specific* Docker container can use while running. Defaults to `8073741824`. + The maximum memory available to each Compose service that applies this limit. It is a per-container upper limit, not the minimum host memory, the total memory reserved by RAGFlow, or a guarantee that every container consumes this amount. The default is `8073741824` bytes, approximately `7.52 GiB` (`8.07 GB`). ### MySQL @@ -70,14 +73,16 @@ The [.env](https://github.com/infiniflow/ragflow/blob/main/docker/.env) file con - `MYSQL_PORT` The port to connect to MySQL from RAGFlow container. Defaults to `3306`. Change this if you use an external MySQL. - `EXPOSE_MYSQL_PORT` - The port used to expose the MySQL service to the host machine, allowing **external** access to the MySQL database running inside the Docker container. Defaults to `5455`. + The port used to expose the MySQL service to the host machine, allowing **external** access to the MySQL database running inside the Docker container. Defaults to `3306`. +- `MYSQL_MAX_PACKET` + The maximum MySQL communication packet size in bytes. Defaults to `1073741824` bytes (`1 GiB`). Keep the MySQL server's `max_allowed_packet` setting compatible when using an external database. ### MinIO RAGFlow utilizes MinIO as its object storage solution, leveraging its scalability to store and manage all uploaded files. - `MINIO_CONSOLE_PORT` - The port used to expose the MinIO console interface to the host machine, allowing **external** access to the web-based console running inside the Docker container. Defaults to `9001` + The port used to expose the MinIO console interface to the host machine, allowing **external** access to the web-based console running inside the Docker container. Defaults to `9001`. - `MINIO_PORT` The port used to expose the MinIO API service to the host machine, allowing **external** access to the MinIO object storage service running inside the Docker container. Defaults to `9000`. - `MINIO_USER` @@ -85,34 +90,51 @@ RAGFlow utilizes MinIO as its object storage solution, leveraging its scalabilit - `MINIO_PASSWORD` The password for MinIO. -### Redis +### Kvrocks -- `REDIS_PORT` - The port used to expose the Redis service to the host machine, allowing **external** access to the Redis service running inside the Docker container. Defaults to `6379`. -- `REDIS_USERNAME` - Optional Redis ACL username when using Redis 6+ authentication. +Kvrocks provides the Redis-compatible cache. It is separate from the NATS JetStream message queue. + +- `KVROCKS_HOST` + The hostname used by the Go services. Keep the default `kvrocks` when using the provided Compose deployment. +- `KVROCKS_PORT` + The host port mapped to the Kvrocks container port `6379`. Defaults to `6379`. - `REDIS_PASSWORD` - The password for Redis. + The password used to access Kvrocks through its Redis-compatible protocol. + +### NATS + +NATS JetStream provides the message queue used by the Go services. + +- `NATS_HOST` + The NATS hostname used inside the Compose network. Defaults to `nats`. +- `NATS_PORT` + The internal NATS client port. Defaults to `4222`. +- `EXPOSE_NATS_PORT` + The NATS port published on the Docker host. ### RAGFlow - `SVR_HTTP_PORT` - The port used to expose RAGFlow's HTTP API service to the host machine, allowing **external** access to the service running inside the Docker container. Defaults to `9380`. + The target Go API port published by Compose. Defaults to `9380`. Normal browser and API traffic should use the public Nginx port unless direct access is required. +- `ADMIN_SVR_HTTP_PORT` + The target Go Admin port published by Compose. Defaults to `9381`. +- `SVR_WEB_HTTP_PORT`, `SVR_WEB_HTTPS_PORT` + The public Nginx ports. Defaults to `80` and `443`. - `RAGFLOW_IMAGE` - The Docker image edition. Defaults to `infiniflow/ragflow:v0.27.2` (the RAGFlow Docker image without embedding models). + The Go RAGFlow image used by `docker-compose.yml`. Select the official Go image for the required release, or use the locally built `ragflow:go-local` image. :::tip NOTE If you cannot download the RAGFlow Docker image, try the following mirrors. -- For the `nightly` edition: - - `RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:nightly` or, - - `RAGFLOW_IMAGE=registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:nightly`. - ::: +- `RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:nightly` +- `RAGFLOW_IMAGE=registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:nightly` + +::: ### Embedding Service - `TEI_MODEL` - The embedding model which text-embeddings-inference serves. Allowed values are one of `Qwen/Qwen3-Embedding-0.6B`(default), `BAAI/bge-m3`, and `BAAI/bge-small-en-v1.5`. + The embedding model served by the optional local text-embeddings-inference service. Its memory requirement depends on the model, runtime backend, precision, batch-token limit, and concurrency. The `tei-cpu` profile uses system RAM; the `tei-gpu` profile primarily uses GPU memory and also consumes system RAM. Verify peak usage on the target hardware and reserve additional host memory for RAGFlow and the other enabled services. - `TEI_PORT` The port used to expose the text-embeddings-inference service to the host machine, allowing **external** access to the text-embeddings-inference service running inside the Docker container. Defaults to `6380`. @@ -134,17 +156,13 @@ If you cannot download the RAGFlow Docker image, try the following mirrors. ### User Registration -- `REGISTER_ENABLED` +- `ENABLE_REGISTER` - `1`: (Default) Enable user registration. - `0`: Disable user registration. -- `OAUTH_AUTO_REGISTER` - - `true`: (Default) Allow new users to be provisioned on OAuth/OIDC login. Also accepts `1`, `yes`, `on`. - - Any other value, `false` included: require OAuth/OIDC users to already exist. This is independent of `REGISTER_ENABLED`. - ## Service Configuration -[service_conf.yaml.template](https://github.com/infiniflow/ragflow/blob/main/docker/service_conf.yaml.template) specifies the system-level configuration for RAGFlow and is used by its API server and task executor. +[service_conf.yaml.template](https://github.com/infiniflow/ragflow/blob/main/docker/service_conf.yaml.template) specifies the system-level configuration used by the Go API, Admin, Ingestor, and Syncer services. ### `ragflow` @@ -158,8 +176,9 @@ If you cannot download the RAGFlow Docker image, try the following mirrors. - `user`: The username for MySQL. - `password`: The password for MySQL. - `port`: The MySQL serving port inside the Docker container. Defaults to `3306`. -- `max_connections`: The maximum number of concurrent connections to the MySQL database. Defaults to `100`. -- `stale_timeout`: Timeout in seconds. +- `max_connections`: The maximum number of concurrent connections in the MySQL connection pool. Defaults to `900` in the Go deployment configuration. +- `stale_timeout`: The connection stale timeout in seconds. Defaults to `300` in the Go deployment configuration. +- `max_allowed_packet`: The maximum communication packet size in bytes. Defaults to `1073741824` bytes (`1 GiB`). ### `minio` @@ -193,72 +212,13 @@ When using an external storage backend, you can remove the `minio` service from For other S3-compatible backends (AWS S3, Alibaba Cloud OSS, Azure Blob, Google Cloud Storage), see the commented examples in [service_conf.yaml.template](https://github.com/infiniflow/ragflow/blob/main/docker/service_conf.yaml.template). -### `redis` +### `kvrocks` -- `host`: The Redis serving IP *and* port inside the Docker container. Defaults to `redis:6379`. -- `db`: The Redis database index to use. Defaults to `1`. -- `username`: Optional Redis ACL username (Redis 6+). -- `password`: The password for the specified Redis user. +- `host`: The Kvrocks address used by the Go services. Defaults to `kvrocks:6379` in the Compose deployment. +- `db`: The logical database index. Defaults to `1`. +- `username`: Optional Kvrocks ACL username. +- `password`: The password used by the Go services to access Kvrocks. -### `oauth` +### Configure model providers -The OAuth configuration for signing up or signing in to RAGFlow using a third-party account. - -- ``: Custom channel ID. - - `type`: Authentication type, options include `oauth2`, `oidc`, `github`. Default is `oauth2`, when `issuer` parameter is provided, defaults to `oidc`. - - `icon`: Icon ID, options include `github`, `sso`, default is `sso`. - - `display_name`: Channel name, defaults to the Title Case format of the channel ID. - - `client_id`: Required, unique identifier assigned to the client application. - - `client_secret`: Required, secret key for the client application, used for communication with the authentication server. - - `authorization_url`: Base URL for obtaining user authorization. - - `token_url`: URL for exchanging authorization code and obtaining access token. - - `userinfo_url`: URL for obtaining user information (username, email, etc.). - - `issuer`: Base URL of the identity provider. OIDC clients can dynamically obtain the identity provider's metadata (`authorization_url`, `token_url`, `userinfo_url`) through `issuer`. - - `scope`: Requested permission scope, a space-separated string. For example, `openid profile email`. - - `redirect_uri`: Required, URI to which the authorization server redirects during the authentication flow to return results. Must match the callback URI registered with the authentication server. Format: `https://your-app.com/api/v1/auth/oauth//callback`. For local configuration, you can directly use `http://127.0.0.1:80/api/v1/auth/oauth//callback`. - -:::tip NOTE -The following are best practices for configuring various third-party authentication methods. You can configure one or multiple third-party authentication methods for Ragflow: -```yaml -oauth: - oauth2: - display_name: "OAuth2" - client_id: "your_client_id" - client_secret: "your_client_secret" - authorization_url: "https://your-oauth-provider.com/oauth/authorize" - token_url: "https://your-oauth-provider.com/oauth/token" - userinfo_url: "https://your-oauth-provider.com/oauth/userinfo" - redirect_uri: "https://your-app.com/api/v1/auth/oauth/oauth2/callback" - - oidc: - display_name: "OIDC" - client_id: "your_client_id" - client_secret: "your_client_secret" - issuer: "https://your-oauth-provider.com/oidc" - scope: "openid email profile" - redirect_uri: "https://your-app.com/api/v1/auth/oauth/oidc/callback" - - github: - # https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app - type: "github" - icon: "github" - display_name: "Github" - client_id: "your_client_id" - client_secret: "your_client_secret" - redirect_uri: "https://your-app.com/api/v1/auth/oauth/github/callback" -``` -::: - -### `user_default_llm` - -Assigning default models to newly registered users through `user_default_llm` is deprecated and no longer supported in the open-source version. Uncommenting this section in **service_conf.yaml.template** does not configure models for new users. - -Each tenant must configure its own model provider instances and credentials. New users do not automatically inherit an administrator's configured instances or default model selections. - -Go to **User settings** **>** **Model providers** to configure provider instances, add models, and select default models. See [Configure Model API Key](../../guides/models/llm_api_key_setup.md) for instructions. - -The Enterprise Edition provides role-level default model settings. - -:::note Builtin embedding -If you deploy TEI, keep the shipped `user_default_llm.default_models.embedding_model` connection settings in **service_conf.yaml.template**. They are used by the TEI `Builtin` embedding service and do not assign administrator-owned model instances to new tenants. -::: +Go to **User settings** **>** **Model providers** to configure provider credentials, add models, and select the default models for the current account. See [Configure Model API Key](../../guides/models/llm_api_key_setup.md) for instructions. diff --git a/docs/administrator/configurations/sandbox_quickstart.md b/docs/administrator/configurations/sandbox_quickstart.md index 8234ac8b36..b5216fc0bc 100644 --- a/docs/administrator/configurations/sandbox_quickstart.md +++ b/docs/administrator/configurations/sandbox_quickstart.md @@ -24,20 +24,14 @@ The simplest setup flow is: Configure sandbox providers from the admin page: - `self_managed`: Uses the executor manager service. -- `local`: Runs code on the current machine. - `ssh`: Runs code on a remote machine over SSH. - `aliyun_codeinterpreter`, `e2b`, and `tenki`: Cloud providers. -admin-sandbox-settings - ## Provider options - -RAGFlow supports multiple sandbox providers. Configure the active provider in -Admin > Sandbox Settings after the services are up. +RAGFlow supports multiple sandbox providers. Configure the active provider in Admin > Sandbox Settings after the services are up. - `self_managed`: Runs code inside Docker-managed sandbox containers. This is the default provider. -- `local`: Runs code as local Python or Node.js subprocesses. Use this only in trusted development environments. - `ssh`: Runs code on a remote machine over SSH. - `aliyun_codeinterpreter` and `e2b`: Cloud-hosted providers that remain available in the admin provider list. - `tenki`: Cloud-hosted provider that runs each execution in a disposable [Tenki](https://tenki.cloud) microVM. See [Tenki](#tenki) below. @@ -46,12 +40,6 @@ Admin > Sandbox Settings after the services are up. `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. -The `tenki-sandbox` SDK is an optional dependency (it requires `protobuf>=6.31`, which differs from RAGFlow's default gRPC stack), so it is not installed by default. Install it into the RAGFlow runtime before selecting this provider: - -```bash -pip install tenki-sandbox -``` - Configure it in **Admin > Sandbox Settings**: - `api_key` (required): Tenki API key. Create one at [app.tenki.cloud](https://app.tenki.cloud) under **API Keys**. @@ -67,7 +55,9 @@ Notes: - Files written to the `artifacts/` directory of the working directory are returned as run artifacts. - The provider uses only Tenki's create/exec/destroy operations; it does not use volumes or snapshots. -## Prerequisites +## Self-Managed prerequisites + +The following prerequisites apply only when you use the `self_managed` provider: - Linux distribution compatible with gVisor. - gVisor installed and configured. @@ -126,21 +116,18 @@ docker compose -f docker-compose.yml up -d ## Running with RAGFlow -1. Verify that gVisor is properly installed and operational. +1. If you use the `self_managed` provider, verify that gVisor is installed and operational. -2. Configure the .env file located at docker/.env: +2. Configure **docker/.env**: -- Set `SANDBOX_ENABLED=1`. -- Include `sandbox` in `COMPOSE_PROFILES` if you want the default - `self_managed` executor-manager service. -- Keep the self-managed deployment defaults in `.env` if you need to change the - sandbox-executor-manager image, pool size, base images, seccomp, memory, or - timeout. +- Include `sandbox` in `COMPOSE_PROFILES` if you want the default `self_managed` executor-manager service. +- If you use the `ssh` provider, set `RAGFLOW_SSH_KNOWN_HOSTS` to the host `known_hosts` file and keep `SSH_KNOWN_HOSTS` as the path used inside the Go container. The default values are `${HOME}/.ssh/known_hosts` and `/etc/ragflow/ssh_known_hosts`. +- Keep the self-managed deployment defaults in `.env` if you need to change the sandbox-executor-manager image, pool size, base images, seccomp, memory, or timeout. 3. Add the following entry to your /etc/hosts file to resolve the executor manager service: ```bash - 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager + 127.0.0.1 es01 infinity mysql minio kvrocks sandbox-executor-manager ``` 4. Start the RAGFlow service as usual. @@ -156,26 +143,25 @@ The variables in `docker/.env` are grouped by scope. ### System-level variables -These variables apply to sandbox support in general: +These variables apply to the sandbox deployment: -- `SANDBOX_ENABLED`: Enables sandbox support in RAGFlow. - `COMPOSE_PROFILES`: Include `sandbox` to start the default self-managed executor-manager service. - `SANDBOX_ARTIFACT_BUCKET`: MinIO bucket used for files generated by sandbox code. -- `SANDBOX_ARTIFACT_EXPIRE_DAYS`: Number of days before sandbox artifacts expire. ### Self-managed deployment defaults -These variables are shown in Admin as deployment defaults for `self_managed`. -Changing them requires restarting `sandbox-executor-manager`. +These variables are shown in Admin as deployment defaults for `self_managed`. Changing them requires restarting `sandbox-executor-manager`. -- `SANDBOX_EXECUTOR_MANAGER_IMAGE`: Docker image for the executor manager service. -- `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE`: Number of Python and Node.js sandbox containers kept in the pool. -- `SANDBOX_BASE_PYTHON_IMAGE`: Python runtime image used by executor-managed containers. -- `SANDBOX_BASE_NODEJS_IMAGE`: Node.js runtime image used by executor-managed containers. -- `SANDBOX_EXECUTOR_MANAGER_PORT`: Host port exposed by the executor manager. -- `SANDBOX_ENABLE_SECCOMP`: Enables the optional seccomp profile for sandbox containers. -- `SANDBOX_MAX_MEMORY`: Memory limit for each sandbox runtime container. -- `SANDBOX_TIMEOUT`: Default execution timeout. +- `SANDBOX_EXECUTOR_MANAGER_IMAGE`: Docker image for the executor manager service. Defaults to `infiniflow/sandbox-executor-manager:latest`. +- `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE`: Number of Python and Node.js sandbox containers kept in each runtime pool. Defaults to `3`. +- `SANDBOX_BASE_PYTHON_IMAGE`: Python runtime image used by executor-managed containers. Defaults to `infiniflow/sandbox-base-python:latest`. +- `SANDBOX_BASE_NODEJS_IMAGE`: Node.js runtime image used by executor-managed containers. Defaults to `infiniflow/sandbox-base-nodejs:latest`. +- `SANDBOX_EXECUTOR_MANAGER_PORT`: Host port exposed by the executor manager. Defaults to `9385` and binds to `127.0.0.1` in the provided Compose configuration. +- `SANDBOX_ENABLE_SECCOMP`: Enables the optional seccomp profile for sandbox containers. Defaults to `false`. +- `SANDBOX_MAX_MEMORY`: Memory limit for each sandbox runtime container. Defaults to `256m`; it is not the total memory limit for all sandbox containers. +- `SANDBOX_CONTAINER_NETWORK`: Docker network attached to each sandbox runtime container. Defaults to `none`, which prevents external network access. Use `bridge` only when sandboxed code needs outbound network access. +- `SANDBOX_TIMEOUT`: Default execution timeout. Defaults to `10s`. +- `SANDBOX_EXECUTOR_MANAGER_API_TOKEN`: Shared secret used to authenticate requests from RAGFlow to the executor manager. Set a strong value for network-accessible deployments; the same value is passed to both services by the provided Compose configuration. ### Admin-managed runtime settings @@ -185,7 +171,6 @@ Examples: - Choose the active provider - Configure `self_managed` runtime settings -- Configure all `local` settings - Configure all `ssh` settings For `self_managed`: diff --git a/docs/administrator/migration/backup_and_migration.md b/docs/administrator/migration/backup_and_migration.md index 74f684817d..27ead697e1 100644 --- a/docs/administrator/migration/backup_and_migration.md +++ b/docs/administrator/migration/backup_and_migration.md @@ -1,334 +1,102 @@ --- sidebar_position: 2 -title: "Backup & Migration" -sidebar_label: "Backup & Migration" +title: "Go Backup and Migration" +sidebar_label: "Go Backup and Migration" slug: /migration sidebar_custom_props: { categoryIcon: LucideLocateFixed } --- -# Backup & Migration +# Go Backup and Migration -- [Data migration](#data-migration) -- [Migrate from multi-bucket to single-bucket mode](#migrate-from-multi-bucket-to-single-bucket-mode) +This guide explains how to move the default Go Docker deployment to another host. -## Data Migration +The bundled `docker/migration.sh` covers only the MySQL, MinIO, Redis, and Elasticsearch volumes and is not a complete backup method for the Go Docker deployment. It does not include Kvrocks or optional service volumes. Use the volume procedure below to back up a Go deployment. -:::info KUDOS -This document is contributed by our community contributor [TreeDy](https://github.com/Treedy2020). We may not actively maintain this document. -::: +## Move a Go deployment to another host -A common scenario is processing large datasets on a powerful instance (e.g., with a GPU) and then migrating the entire RAGFlow service to a different production environment (e.g., a CPU-only server). This guide explains how to safely back up and restore your data using our provided migration script. +### 1. Identify all persistent data -### Identify Your Data - -By default, RAGFlow uses Docker volumes to store all persistent data, including your database, uploaded files, and search indexes. You can see these volumes by running: +From the repository root, inspect the running deployment and its Docker volumes: ```bash +docker compose --env-file docker/.env -f docker/docker-compose.yml ps docker volume ls ``` -The output will look similar to this: +Record the Compose project name and the volumes actually mounted by its running containers before stopping them. For each relevant container shown by `ps`, check its mounts with `docker inspect --format '{{range .Mounts}}{{println .Name .Destination}}{{end}}'`. `docker volume ls` also shows unrelated and unused volumes, so do not treat that list as the backup set. The default project name is usually `docker`; if you started Compose with `-p ragflow`, volume names normally start with `ragflow_`. Use the same `-p` value with every Compose command below. -```text -DRIVER VOLUME NAME -local docker_esdata01 -local docker_minio_data -local docker_mysql_data -local docker_redis_data -``` +The default Go stack can use these volumes, depending on the enabled services: -These volumes contain all the data you need to migrate. +| Service or data | Typical volume | +| --- | --- | +| Metadata database | `_mysql_data` | +| Uploaded objects in bundled MinIO | `_minio_data` | +| Search index with Elasticsearch | `_esdata01` | +| Go cache and persistent Redis-protocol data | `_kvrocks_data` | +| NATS JetStream data | `_nats_data` | +| ClickHouse analytics data | `_clickhouse_data` | -:::note -The volume name prefix (e.g., `docker_`) comes from the Docker Compose project name. By default it is `docker` (derived from the directory name). If you started RAGFlow with `docker compose -p `, your volumes will be prefixed with `_` instead, for example `ragflow_mysql_data`. -::: +Also retain `docker/.env`, the configuration template, and any custom certificates or mounted files. Protect the backup because these files may contain credentials. -### Step 1: Stop RAGFlow Services +### 2. Stop writers and archive the volumes -Before starting the migration, you must stop all running RAGFlow services on the **source machine**. Navigate to the project's root directory and run: +Stop the Go deployment and any other process that writes to the same stores. For a Compose project named `docker`: ```bash -docker compose -f docker/docker-compose.yml down +docker compose --env-file docker/.env -f docker/docker-compose.yml down +mkdir backup-go ``` -If you started RAGFlow with a custom project name (e.g., `docker compose -p ragflow`), include it in the command: +Create a new, empty `backup-go` directory for this backup; do not reuse a directory containing earlier archives. Repeat the following command for **each volume you recorded**. Replace `docker_mysql_data` with its exact name; the example creates `backup-go/docker_mysql_data.tar.gz`: ```bash -docker compose -p ragflow -f docker/docker-compose.yml down +volume_name=docker_mysql_data +if docker volume inspect "$volume_name" >/dev/null 2>&1; then + if docker run --rm -v "$volume_name":/source:ro -v "$PWD/backup-go":/backup alpine:3.20 \ + tar czf "/backup/$volume_name.tar.gz" -C /source .; then + tar tzf "backup-go/$volume_name.tar.gz" > /dev/null + else + echo "Backup failed: $volume_name" + fi +else + echo "Missing volume: $volume_name" +fi ``` -**Important:** Do **not** use the `-v` flag (e.g., `docker compose down -v`), as this will delete all your data volumes. The migration script includes a check and will prevent you from running it if services are active. +Keep the volume name in each archive filename and copy the entire `backup-go` directory to the target host. Verify that every selected volume has a readable archive. -### Step 2: Back Up Your Data +### 3. Restore on the target host -We provide a convenient script to package all your data volumes into a single backup folder. +Install the matching Go deployment and configuration on the target host. Keep services stopped and put `backup-go` in the repository root. -For a quick reference of the script's commands and options, you can run: -```bash -bash docker/migration.sh help -``` - -To create a backup, run the following command from the project's root directory: +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: ```bash -bash docker/migration.sh backup +source_volume=docker_mysql_data +target_volume=docker_mysql_data +if ! test -f "backup-go/$source_volume.tar.gz"; then + echo "Missing archive: backup-go/$source_volume.tar.gz" +elif docker volume inspect "$target_volume" >/dev/null 2>&1; then + echo "Target volume already exists; inspect it before restoring: $target_volume" +else + if docker volume create "$target_volume"; then + docker run --rm -v "$target_volume":/target -v "$PWD/backup-go":/backup:ro alpine:3.20 \ + tar xzf "/backup/$source_volume.tar.gz" -C /target + fi +fi ``` -This will create a `backup/` folder in your project root containing compressed archives of your data volumes. +If the target Compose project has a different name, set `target_volume` to that project's volume name while retaining `source_volume` from the archive. Do not restore over a populated volume: extracting an archive does not remove files already present. Keep the metadata database, object data, and search index from the same stopped deployment together. -You can also specify a custom name for your backup folder: +### 4. Start and verify + +Start the Go stack with the target configuration and the same Compose project name used for its volumes: ```bash -bash docker/migration.sh backup my_ragflow_backup +docker compose --env-file docker/.env -f docker/docker-compose.yml up -d +docker compose --env-file docker/.env -f docker/docker-compose.yml ps ``` -This will create a folder named `my_ragflow_backup/` instead. - -If you started RAGFlow with a custom project name (e.g., `docker compose -p ragflow`), use the `-p` flag so the script can find the correct volumes: - -```bash -bash docker/migration.sh -p ragflow backup -bash docker/migration.sh -p ragflow backup my_ragflow_backup -``` - -### Step 3: Transfer the Backup Folder - -Copy the entire backup folder (e.g., `backup/` or `my_ragflow_backup/`) from your source machine to the RAGFlow project directory on your **target machine**. You can use tools like `scp`, `rsync`, or a physical drive for the transfer. - -### Step 4: Restore Your Data - -On the **target machine**, ensure that RAGFlow services are not running. Then, use the migration script to restore your data from the backup folder. - -If your backup folder is named `backup/`, run: - -```bash -bash docker/migration.sh restore -``` - -If you used a custom name, specify it in the command: - -```bash -bash docker/migration.sh restore my_ragflow_backup -``` - -If the target machine uses a custom project name, use the `-p` flag to ensure the volumes are created with the correct prefix: - -```bash -bash docker/migration.sh -p ragflow restore -bash docker/migration.sh -p ragflow restore my_ragflow_backup -``` - -The script will automatically create the necessary Docker volumes and unpack the data. - -**Note:** If the script detects that Docker volumes with the same names already exist on the target machine, it will warn you that restoring will overwrite the existing data and ask for confirmation before proceeding. - -### Step 5: Start RAGFlow Services - -Once the restore process is complete, you can start the RAGFlow services on your new machine: - -```bash -docker compose -f docker/docker-compose.yml up -d -``` - -If you use a custom project name: - -```bash -docker compose -p ragflow -f docker/docker-compose.yml up -d -``` - -**Note:** If you already have built a service by docker compose before, you may need to backup your data for target machine like this guide above and run like: - -```bash -# Please backup by `bash docker/migration.sh backup backup_dir_name` before you do the following line. -# !!! this line -v flag will delete the original docker volume -docker compose -f docker/docker-compose.yml down -v -docker compose -f docker/docker-compose.yml up -d -``` - -Your RAGFlow instance is now running with all the data from your original machine. - -## Migrate from Multi-Bucket to Single-Bucket Mode - -:::info KUDOS -This document is contributed by our community contributor [arogan178](https://github.com/arogan178). We may not actively maintain this document. -::: - -By default, RAGFlow creates one bucket per Knowledge Base (dataset) and one bucket per user folder. This can be problematic when: - -- Your cloud provider charges per bucket -- Your IAM policy restricts bucket creation -- You want all data organized in a single bucket with directory structure - -The **Single Bucket Mode** allows you to configure RAGFlow to use a single bucket with a directory structure instead of multiple buckets. - -### How It Works - -#### Default Mode (Multiple Buckets) - -``` -bucket: kb_12345/ - └── document_1.pdf -bucket: kb_67890/ - └── document_2.pdf -bucket: folder_abc/ - └── file_3.txt -``` - -#### Single Bucket Mode (With Prefix_path) - -``` -bucket: ragflow-bucket/ - └── ragflow/ - ├── kb_12345/ - │ └── document_1.pdf - ├── kb_67890/ - │ └── document_2.pdf - └── folder_abc/ - └── file_3.txt -``` - -### Configuration - -#### MinIO Configuration - -Edit your `service_conf.yaml` or set environment variables: - -```yaml -minio: - user: "your-access-key" - password: "your-secret-key" - host: "minio.example.com:443" - bucket: "ragflow-bucket" # Default bucket name - prefix_path: "ragflow" # Optional prefix path -``` - -Or using environment variables: - -```bash -export MINIO_USER=your-access-key -export MINIO_PASSWORD=your-secret-key -export MINIO_HOST=minio.example.com:443 -export MINIO_BUCKET=ragflow-bucket -export MINIO_PREFIX_PATH=ragflow -``` - -#### S3 Configuration (Already Supported) - -```yaml -s3: - access_key: "your-access-key" - secret_key: "your-secret-key" - endpoint_url: "https://s3.amazonaws.com" - bucket: "my-ragflow-bucket" - prefix_path: "production" - region_name: "us-east-1" -``` - -#### Tigris Configuration - -[Tigris](https://www.tigrisdata.com) is an S3-compatible object storage service that works with RAGFlow's `AWS_S3` backend. Set `STORAGE_IMPL=AWS_S3` in your `.env` file: - -```yaml -s3: - access_key: "tid_YOUR_ACCESS_KEY" - secret_key: "tsec_YOUR_SECRET_KEY" - region_name: "auto" - endpoint_url: "https://t3.storage.dev" - bucket: "ragflow" - prefix_path: "ragflow" - signature_version: "v4" - addressing_style: "virtual" -``` - -See [S3 (Tigris)](../configurations/configurations.md#s3-tigris) for full setup instructions. - -### Iam Policy Example - -When using single bucket mode, you only need permissions for one bucket: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": ["s3:*"], - "Resource": [ - "arn:aws:s3:::ragflow-bucket", - "arn:aws:s3:::ragflow-bucket/*" - ] - } - ] -} -``` - -### Migration from Multi-Bucket to Single Bucket - -If you're migrating from multi-bucket mode to single-bucket mode: - -1. **Set environment variables** for the new configuration -2. **Restart RAGFlow** services -3. **Migrate existing data** (optional): - -```bash -# Example using mc (MinIO Client) -mc alias set old-minio http://old-minio:9000 ACCESS_KEY SECRET_KEY -mc alias set new-minio https://new-minio:443 ACCESS_KEY SECRET_KEY - -# List all knowledge base buckets -mc ls old-minio/ | grep kb_ | while read -r line; do - bucket=$(echo $line | awk '{print $5}') - # Copy each bucket to the new structure - mc cp --recursive old-minio/$bucket/ new-minio/ragflow-bucket/ragflow/$bucket/ -done -``` - -### Toggle Between Modes - -#### Enable Single Bucket Mode - -```yaml -minio: - bucket: "my-single-bucket" - prefix_path: "ragflow" -``` - -#### Disable (Use Multi-Bucket Mode) - -```yaml -minio: - # Leave bucket and prefix_path empty or commented out - # bucket: '' - # prefix_path: '' -``` - -### Troubleshooting - -#### Issue: Access Denied Errors - -**Solution**: Ensure your IAM policy grants access to the bucket specified in the configuration. - -#### Issue: Files Not Found After Switching Modes - -**Solution**: The path structure changes between modes. You'll need to migrate existing data. - -#### Issue: Connection Fails with HTTPS - -**Solution**: Ensure `secure: True` is set in the MinIO connection (automatically handled for port 443). - -### Storage Backends Supported - -- ✅ **MinIO** - Full support with single bucket mode -- ✅ **AWS S3** - Full support with single bucket mode -- ✅ **Tigris** - Full support with single bucket mode (uses `AWS_S3` backend) -- ✅ **Alibaba OSS** - Full support with single bucket mode -- ✅ **Azure Blob** - Uses container-based structure (different paradigm) -- ⚠️ **OpenDAL** - Depends on underlying storage backend - -### Performance Considerations - -- **Single bucket mode** may have slightly better performance for bucket listing operations -- **Multi-bucket mode** provides better isolation and organization for large deployments -- Choose based on your specific requirements and infrastructure constraints +The Go image's entrypoint runs the standalone database migration before starting its enabled server modes. Check the container logs for migration errors before using the service. Confirm that an existing dataset can list and open files and that search still returns its documents. diff --git a/docs/administrator/migration/database_change_log.md b/docs/administrator/migration/database_change_log.md index e1b5f6face..628cbbcf43 100644 --- a/docs/administrator/migration/database_change_log.md +++ b/docs/administrator/migration/database_change_log.md @@ -15,7 +15,7 @@ A version-by-version record of the schema and data changes the Go backend applie ## How the database version is recorded - The marker is a row in `system_settings` with the key `mysql_migration.database.version`. -- The same marker is written by the Python script [run_migrations.sh](https://github.com/infiniflow/ragflow/blob/main/tools/scripts/run_migrations.sh), so a step already performed by Python is skipped by Go, and vice versa. +- The marker prevents a migration step from running again after that step has completed successfully. - Go defines the versions as constants: `modelMigrationBaseVersion` and `modelMigrationTargetVersion` in [migration_version.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/migration_version.go), and `conversationHistoryTargetVersion` in [conversation_history_migration.go](https://github.com/infiniflow/ragflow/blob/main/internal/dao/conversation_history_migration.go). - A step runs when the stored version is lower than the step's version. Versions are compared with Python PEP 440 semantics, where a `dev` prerelease sorts *before* the release it precedes (`v1.0.0-rc1.dev1` < `v1.0.0-rc1`). A missing or unparsable marker never skips a step. - `checkDatabaseVersion` in [cmd/ragflow_server.go](https://github.com/infiniflow/ragflow/blob/main/cmd/ragflow_server.go) refuses to start when the code version is older than the stored database version, so a database migrated by a newer release cannot be opened by an older one. @@ -29,11 +29,11 @@ Startup order in `InitDB` ([database.go](https://github.com/infiniflow/ragflow/b ## Version overview -| Database version | Scope | Gate constant | Minimum compatible RAGFlow version | -|---|---|---|---| -| `v0.26.0` | Rebuild the tenant model tables from `tenant_llm` and normalize stored model ids | `modelMigrationBaseVersion` | `_TBD_` | -| `v0.27.2` | Seed factory-declared models, merge `model_type` into an integer bitmask, populate the `tenant_*_id` columns | `modelMigrationTargetVersion` | `_TBD_` | -| `v1.0.0-rc1.dev1` | Split conversation message and reference payloads into child tables | `conversationHistoryTargetVersion` | `_TBD_` | +| Database version | Scope | Gate constant | +|---|---|---| +| `v0.26.0` | Rebuild the tenant model tables from `tenant_llm` and normalize stored model ids | `modelMigrationBaseVersion` | +| `v0.27.2` | 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 `v0.27.2` step, and a database at or above `v0.27.2` runs neither. @@ -41,8 +41,6 @@ The two tenant model steps are cumulative: a database at `v0.26.0` still runs th ## v0.26.0 -**Minimum compatible RAGFlow version:** `_TBD_` - ### Schema changes | Object | Change | @@ -69,8 +67,6 @@ On success the step writes `v0.26.0` into the version marker. ## v0.27.2 -**Minimum compatible RAGFlow version:** `_TBD_` - ### Schema changes | Table | Change | @@ -97,8 +93,6 @@ On success the step writes `v0.27.2` into the version marker. ## v1.0.0-rc1.dev1 -**Minimum compatible RAGFlow version:** `_TBD_` - This step only prepares the schema owned by `v1.0.0-rc1`; dropping the legacy payload columns is out of its scope. ### Schema changes diff --git a/docs/administrator/migration/database_schema_and_migration.md b/docs/administrator/migration/database_schema_and_migration.md index 8dba51813d..7f50ad39d9 100644 --- a/docs/administrator/migration/database_schema_and_migration.md +++ b/docs/administrator/migration/database_schema_and_migration.md @@ -10,49 +10,39 @@ sidebar_custom_props: { # Database Schema and Migration -Sync schemas and migrate data using official RAGFlow scripts. +For a manually started Go backend, run database migration as a standalone step before starting any server process: ---- +```bash +./bin/ragflow_server --migrate +``` -RAGFlow handles schema updates and migrations automatically at startup. However, for high-volume environments like Kubernetes, massive datasets can cause initialization to exceed 10 minutes, potentially triggering container timeouts or health check failures. To avoid this, you can disable the built-in auto-initialization and manually run these provided scripts to complete database upgrades before launching the service: +The command loads the same database configuration as the Go server, applies schema and data changes, then exits. Use `-f` or `--config` to select a configuration file when needed. Do not combine `--migrate` with `--admin`, `--api`, `--ingestor`, or `--syncer`. Allow enough time for data backfills and schema changes on large databases. -- [mysql_migration.py](#mysql_migrationpy): Migrates data between MySQL tables. -- [db_schema_sync.py](#db_schema_syncpy): Syncs database schemas and manages changes using peewee-migrate. +The migration process does not start a server mode or initialize the document engine, Kvrocks cache, object storage, or NATS JetStream message queue. It needs access to the configured metadata database and local configuration files. Run it where `conf/models` is available: database initialization loads the model provider definitions from that relative path and fails if the directory cannot be read. The model data migration also tries to read `conf/llm_factories.json`; if the file is absent or unreadable, that input is skipped. Keep the matching configuration files with the new binary. -## Mysql_migration.py +## Where migrations are defined -The [mysql_migration.py](https://github.com/infiniflow/ragflow/blob/main/tools/scripts/mysql_migration.py) script is a specialized tool for re-organizing RAGFlow’s model-related data. It transitions data from older unified tables into a modern, multi-table structure to support advanced model management. +Go migration logic lives in `internal/dao/`. `database.go` runs the migration sequence: manual changes in `migration.go` and related files, GORM `AutoMigrate` for the Go entities in `internal/entity/`, and the conversation history backfill. Model provider data migration is in `model_migration.go`; its version handling is in `migration_version.go`. These are Go source files, not a directory of generated, numbered SQL migration files. -### Key Functions +The standalone command runs the full sequence. Ordinary server startup connects to the database and may create or update a limited set of runtime tables, but does not run the full manual and data migration sequence. Do not rely on server startup to perform an upgrade. -- **Sequential migration**: Moves data through three distinct stages—Provider, Instance, and Model—to maintain database integrity and satisfy dependencies. -- **Flexible setup**: Connects to MySQL using either a YAML configuration file or direct command-line arguments. -- **Execution control**: Offers three specific modes: dry-run (preview), table-only (structural setup), and execute (full data move). -- **Automated mapping**: Generates unique IDs and handles complex joins between legacy records and new table structures. -- **Batch logging**: Processes records in sets of 100 and provides a final summary of total duration and row counts. +## Database version and startup check -### When to Use +The Go migration marker is stored in `system_settings` under the fixed key `mysql_migration.database.version`. The key name is retained for database compatibility and does not select another migration implementation. The Go implementation writes `v0.26.0` after the base tenant-model step and `v0.27.2` after the follow-up model-data step. When the stored version is below `v1.0.0-rc1.dev1`, the conversation-history migration writes that value after it completes, even if the old history columns or rows are absent and no data needs copying. A step already covered by the stored version is skipped. The last completed step therefore determines the value that remains in the row. This marker is **not** a complete version number for every table or schema change. A missing or unparseable marker does not prove that the database is up to date. -- **Version upgrades**: Essential when moving to RAGFlow v0.25 or later to ensure your models are correctly categorized in the new schema. -- **Data normalization**: Necessary when consolidating multiple API keys or LLM providers into the updated system format. -- **Kubernetes deployments**: Useful for setting up the database structure independently using the `--create-table-only` flag before main services start. -- **Migration verification**: Used in dry-run mode to identify any legacy records that still need to be moved to the new tables. +Each Go server process compares its code version with this marker after database initialization. That initialization may already have updated runtime tables, indexes, or built-in templates before the check runs. The comparison uses the release-number portion of each version; development suffixes are not used to establish ordering. If the database version is newer, startup fails with `Refusing to start: database was migrated by a newer version`. If the marker is absent or the versions cannot be compared, this downgrade check does not block startup. The check does not apply pending migrations, and the standalone `--migrate` command does not run the downgrade check. Verify the binary and target database before invoking it. -## Db_schema_sync.py +## Upgrade procedure -The [db_schema_sync.py](https://github.com/infiniflow/ragflow/blob/main/tools/scripts/db_schema_sync.py) script is a synchronization utility that ensures your MySQL database structure matches the Peewee ORM models defined in the RAGFlow source code. +1. Back up the metadata database and verify that you can restore it. See [Backup and Migration](./backup_and_migration.md). +2. Stop or drain all Go server processes that use the database. +3. Deploy the new Go binary and its matching configuration. For a manually started deployment, run `./bin/ragflow_server --migrate` against the target database and wait for it to exit before starting servers. In a deployment with multiple replicas, coordinate a single migration job and wait for it to finish before starting the replicas. The Go-only Docker entrypoint runs this command before its enabled Go server modes; account for that behavior when planning a separate migration job. +4. Start `--admin` first, then `--api` and `--ingestor`; start `--syncer` if file synchronization is enabled. -### Key Functions +Check the migration logs as well as the exit status before starting services. Some schema conflicts are logged and skipped, and built-in template seeding failures are logged as warnings; a successful exit alone does not verify every schema change or template row. The migration command can be rerun after a failure, but do not assume every database DDL operation is transactional. Check the error and database state before retrying. The Go backend has no supported automatic rollback command or generated reverse migration. To return to an older release, restore a compatible database backup along with the older binary. -- **Change detection**: Compares Python model definitions in `api/db/db_models.py` against the live database to identify new tables, added fields, or type mismatches. -- **Migration generation**: Automatically creates Python migration files (containing `migrate()` and `rollback()` logic) in version-specific directories (e.g., `tools/migrate/v0_27_2/`). -- **Schema auditing**: Provides a `--diff` command to view structural discrepancies without applying changes. -- **Execution management**: Applies pending migrations to the database to bring it up to date with the current software version. -- **Safety controls**: Prevents accidental data loss by requiring an explicit `--drop` flag to generate `DROP COLUMN` statements for removed fields. +## Development mode -### When to Use +`RAGFLOW_DEV_MODE=true` disables only the code-versus-database downgrade check for Go server processes. It does not run migrations, reverse schema changes, or make an older binary compatible with a newer database. This is especially relevant to development builds: the conversation-history migration records `v1.0.0-rc1.dev1` even when the checkout still reports a `v0.27.x` release. Use it only for a development database in that situation. Set it for each affected server process; keep it unset in production. -- **Version upgrades**: When moving to a new version of RAGFlow that introduces structural database changes. -- **Development**: When modifying `db_models.py` and needing to update your local database without manual SQL. -- **CI/CD pipelines**: To automatically prepare or apply database updates during deployment. -- **Troubleshooting**: When the application fails due to "Unknown column" or "Table not found" errors, indicating a desynchronized schema. +This migration procedure applies to the default MySQL metadata database. diff --git a/docs/administrator/tracing.mdx b/docs/administrator/tracing.mdx index 7d869cd946..cccc3a738f 100644 --- a/docs/administrator/tracing.mdx +++ b/docs/administrator/tracing.mdx @@ -15,13 +15,10 @@ Observability & Tracing with Langfuse. This document is contributed by our community contributor [jannikmaierhoefer](https://github.com/jannikmaierhoefer). 👏 ::: -RAGFlow ships with a built-in [Langfuse](https://langfuse.com) integration so that you can **inspect and debug every retrieval and generation step** of your RAG pipelines in near real-time. - -Langfuse stores traces, spans and prompt payloads in a purpose-built observability backend and offers filtering and visualisations on top. +RAGFlow includes a [Langfuse](https://langfuse.com) integration for recording chat traces and chat-model generation observations. :::info NOTE -• RAGFlow **≥ 0.18.0** (contains the Langfuse connector) -• A Langfuse workspace (cloud or self-hosted) with a _Project Public Key_ and _Secret Key_ +- A Langfuse workspace, either cloud-hosted or self-hosted, with a _Project Public Key_ and _Secret Key_. ::: --- @@ -43,30 +40,28 @@ RAGFlow stores the credentials _per tenant_. You can configure them either via t 1. Log in to RAGFlow and click your avatar in the top-right corner. 2. Select **API ▸ Scroll down to the bottom ▸ Langfuse Configuration**. -3. Fill in you Langfuse **Host**, **Public Key** and **Secret Key**. +3. Fill in your Langfuse **Host**, **Public Key**, and **Secret Key**. 4. Click **Save**. -Once saved, RAGFlow starts emitting traces automatically – no code change required. +Once saved, the Go chat pipeline uses these credentials for chat requests that use a knowledge base or web search. --- ## 3. Run a Pipeline and Watch the Traces -1. Execute any chat or retrieval pipeline in RAGFlow (e.g. the Quickstart demo). +1. Send a message through a Chat configured with a knowledge base or web search. 2. Open your Langfuse project ▸ **Traces**. -3. Filter by **name ~ `ragflow-*`** (RAGFlow prefixes each trace with `ragflow-`). +3. Find the trace named `openai_chat` for the request. -For every user request you will see: +The trace contains: -• a **trace** representing the overall request -• **spans** for retrieval, ranking and generation steps -• the complete **prompts**, **retrieved documents** and **LLM responses** as metadata +- One `openai_chat` trace containing the tenant ID as `userId`, the chat ID as `sessionId`, and metadata indicating whether streaming was enabled and how many knowledge bases were configured. +- One `chat` generation observation containing the model name and the prompt, citation prompt, and model message list as input. +- A completion update for that generation containing the recorded output summary and prompt, completion, and total token counts. - -([Example trace in Langfuse](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/0bde9629-4251-4386-b583-26101b8e7561?timestamp=2025-05-09T19%3A15%3A37.797Z&display=details&observation=823997d8-ac40-40f3-8e7b-8aa6753b499e)) +Langfuse delivery runs asynchronously, so a tracing delivery failure does not stop the chat response. :::tip NOTE -Use Langfuse's diff view to compare prompt versions or drill down into long-running retrievals to identify bottlenecks. +Use the recorded generation input, output, model name, and token usage to inspect a traced chat request. ::: - diff --git a/docs/administrator/upgrade_ragflow.mdx b/docs/administrator/upgrade_ragflow.mdx index fe0c5fc29d..2608ff5127 100644 --- a/docs/administrator/upgrade_ragflow.mdx +++ b/docs/administrator/upgrade_ragflow.mdx @@ -14,7 +14,7 @@ import TabItem from '@theme/TabItem'; Upgrade RAGFlow to `nightly` or the latest, published release. :::info NOTE -Upgrading RAGFlow in itself will *not* remove your uploaded/historical data. However, be aware that `docker compose -f docker/docker-compose.yml down -v` will remove Docker container volumes, resulting in data loss. +Upgrading RAGFlow in itself will *not* remove your uploaded or historical data. However, `docker compose --env-file docker/.env -f docker/docker-compose.yml down -v` removes Docker container volumes and causes data loss. ::: ## Upgrade RAGFlow to `nightly`, the Most Recent, Tested Docker Image @@ -26,7 +26,7 @@ To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker imag 1. Stop the server ```bash - docker compose -f docker/docker-compose.yml down + docker compose --env-file docker/.env -f docker/docker-compose.yml down ``` 2. Update the local code @@ -35,7 +35,7 @@ To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker imag git pull ``` -3. Update **ragflow/docker/.env**: +3. Update **docker/.env**: ```bash RAGFLOW_IMAGE=infiniflow/ragflow:nightly @@ -44,8 +44,8 @@ To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker imag 4. Update RAGFlow image and restart RAGFlow: ```bash - docker compose -f docker/docker-compose.yml pull - docker compose -f docker/docker-compose.yml up -d + docker compose --env-file docker/.env -f docker/docker-compose.yml pull + docker compose --env-file docker/.env -f docker/docker-compose.yml up -d ``` ## Upgrade RAGFlow to Given Release @@ -55,7 +55,7 @@ To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker imag 1. Stop the server ```bash - docker compose -f docker/docker-compose.yml down + docker compose --env-file docker/.env -f docker/docker-compose.yml down ``` 2. Update the local code @@ -70,7 +70,7 @@ To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker imag git checkout -f v0.27.2 ``` -4. Update **ragflow/docker/.env**: +4. Update **docker/.env**: ```bash RAGFLOW_IMAGE=infiniflow/ragflow:v0.27.2 @@ -79,15 +79,15 @@ To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker imag 5. Update the RAGFlow image and restart RAGFlow: ```bash - docker compose -f docker/docker-compose.yml pull - docker compose -f docker/docker-compose.yml up -d + docker compose --env-file docker/.env -f docker/docker-compose.yml pull + docker compose --env-file docker/.env -f docker/docker-compose.yml up -d ``` ## Frequently Asked Questions ### Do I Need to Back Up My Datasets Before Upgrading RAGFlow? -No, you do not need to. Upgrading RAGFlow in itself will *not* remove your uploaded data or dataset settings. However, be aware that `docker compose -f docker/docker-compose.yml down -v` will remove Docker container volumes, resulting in data loss. +No, you do not need to. Upgrading RAGFlow in itself will *not* remove your uploaded data or dataset settings. However, `docker compose --env-file docker/.env -f docker/docker-compose.yml down -v` removes Docker container volumes and causes data loss. ### Upgrade RAGFlow in an Offline Environment (Without Internet Access) diff --git a/docs/basics/agent_context_engine.md b/docs/basics/agent_context_engine.md index b4085cbdf1..dc0d59700a 100644 --- a/docs/basics/agent_context_engine.md +++ b/docs/basics/agent_context_engine.md @@ -25,8 +25,10 @@ This pattern is called Context Engineering. It is deeply tied to expert know-how The mission of an Agent Context Engine is to turn Context Engineering from an “art” into an industrial-grade science. -Deconstructing the Agent Context Engine +## Deconstructing the Agent Context Engine + So, what exactly is an Agent Context Engine? It is a unified, intelligent, and automated platform responsible for the end-to-end process of assembling the optimal context for an LLM or Agent at the moment of inference. It moves from artisanal crafting to industrialized production. + At its core, an Agent Context Engine is built on a triumvirate of next-generation retrieval capabilities, seamlessly integrated into a single service layer: 1. The Knowledge Core (Advanced RAG): This is the evolution of traditional RAG. It moves beyond simple chunk-and-embed to intelligently process static, private enterprise knowledge. Techniques like TreeRAG (building LLM-generated document outlines for "locate-then-expand" retrieval) and GraphRAG (extracting entity networks to find semantically distant connections) work to close the "semantic gap." The engine’s Ingestion Pipeline acts as the ETL for unstructured data, parsing multi-format documents and using LLMs to enrich content with summaries, metadata, and structure before indexing. diff --git a/docs/develop/acquire_ragflow_api_key.md b/docs/develop/acquire_ragflow_api_key.md index 561ab30fa4..33a091bb64 100644 --- a/docs/develop/acquire_ragflow_api_key.md +++ b/docs/develop/acquire_ragflow_api_key.md @@ -9,7 +9,7 @@ sidebar_custom_props: { --- # Acquire RAGFlow API Key -An API key is required for the RAGFlow server to authenticate your HTTP/Python or MCP requests. This document provides instructions on obtaining a RAGFlow API key. +An API key is required for the RAGFlow server to authenticate HTTP or MCP requests. This document provides instructions on obtaining a RAGFlow API key. 1. Click your avatar in the top right corner of the RAGFlow UI to access the configuration page. 2. Click **API** to switch to the **API** page. @@ -18,5 +18,5 @@ An API key is required for the RAGFlow server to authenticate your HTTP/Python o ![ragflow_api_key](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/ragflow_api_key.jpg) :::tip NOTE -See the [RAGFlow HTTP API reference](../references/http_api_reference.md) or the [RAGFlow Python API reference](../references/python_api_reference.md) for a complete reference of RAGFlow's HTTP or Python APIs. +See the [RAGFlow HTTP API reference](../references/http_api_reference.md) for the complete HTTP API reference. ::: diff --git a/docs/develop/build_docker_image.mdx b/docs/develop/build_docker_image.mdx index 9f1fd5bb69..dad1e4c7d8 100644 --- a/docs/develop/build_docker_image.mdx +++ b/docs/develop/build_docker_image.mdx @@ -7,61 +7,95 @@ sidebar_custom_props: { categoryIcon: LucidePackage } --- + # Build RAGFlow Docker Image -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -A guide explaining how to build a RAGFlow Docker image from its source code. By following this guide, you'll be able to create a local Docker image that can be used for development, debugging, or testing purposes. - -## Target Audience - -- Developers who have added new features or modified the existing code and require a Docker image to view and debug their changes. -- Developers seeking to build a RAGFlow Docker image for an ARM64 platform. -- Testers aiming to explore the latest features of RAGFlow in a Docker image. +Build the Go backend and web frontend into a local Docker image for development and testing. The image uses external LLM and embedding services at runtime. ## Prerequisites -- CPU ≥ 4 cores -- RAM ≥ 16 GB -- Disk ≥ 50 GB -- Docker ≥ 24.0.0 & Docker Compose ≥ v2.26.1 +- A recommended starting configuration of 4 CPU cores, 16 GB RAM, and 50 GB free disk space. Actual requirements depend on the selected document engine, local models, build concurrency, and data volume. +- Docker ≥ 24.0.0 with Docker Compose ≥ v2.26.1 and BuildKit +- Access to the `infiniflow/ragflow_deps:latest` and `infiniflow/github_action_runner:latest` images during the build -## Build a Docker Image +The documented Go image target is `linux/amd64`. On an Apple Silicon Mac, Docker Desktop builds and runs this image through x86-64 emulation. -This image is approximately 2 GB in size and relies on external LLM and embedding services. +## Platform support -:::danger IMPORTANT -- While we also test RAGFlow on ARM64 platforms, we do not maintain RAGFlow Docker images for ARM. However, you can build an image yourself on a `linux/arm64` or `darwin/arm64` host machine as well. -- For ARM64 platforms, please upgrade the `xgboost` version in **pyproject.toml** to `1.6.0` and ensure **unixODBC** is properly installed. -::: +- **Linux x86-64:** This is the supported Docker build target. In the RAGFlow open-source 1.0 release, DeepDoc uses CPU inference for layout analysis, OCR, and table recognition. +- **Apple Silicon macOS:** Build and run the `linux/amd64` image through Docker Desktop x86-64 emulation. Document processing and image builds may be slower than on an x86-64 Linux host. +- **Linux ARM64:** A native Go Docker build is not currently supported. The Go image depends on native libraries that are published for Linux x86-64. Use a Linux x86-64 host for a supported native build. +- **Document engines:** Elasticsearch is the default engine in the Compose example. Infinity and other supported engines may have different CPU, GPU, and architecture requirements; verify the selected engine before deployment. + +Before starting the stack, make sure the host ports used by the selected Compose profile are available. At minimum, check the web, metadata database, cache, object storage, and NATS monitoring ports. For the Go deployment, change the corresponding values in `docker/.env`; use `docker/.env` only when a separate command explicitly loads that file. + +## Build the Go image + +Run the build from the repository root. Keep the `.git` directory in the build context: `Dockerfile` uses it to stamp the image version. ```bash git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ragflow_deps -uv run python3 download_deps.py -docker build -f Dockerfile -t infiniflow/ragflow_deps . -cd .. -docker build -f Dockerfile -t infiniflow/ragflow:nightly . +cd ragflow +docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . ``` -## Launch a RAGFlow Service from Docker for macOS +`Dockerfile` builds the Go server and web frontend. `infiniflow/ragflow_deps:latest` supplies document models and tokenizer assets; `infiniflow/github_action_runner:latest` supplies the build toolchain and prebuilt ONNX Runtime libraries. You do not need to build either dependency image separately for this command. -After building the infiniflow/ragflow:nightly image, you are ready to launch a fully-functional RAGFlow service with all the required components, such as Elasticsearch, MySQL, MinIO, Redis, and more. +## Start the service -## Example: Apple M2 Pro (sequoia) +For the default Elasticsearch document engine on Linux, set `vm.max_map_count` to at least 262144 on the Docker host. For macOS, use the Docker Desktop command below instead. -1. Edit Docker Compose Configuration +```bash +sudo sysctl -w vm.max_map_count=262144 +``` -Open the `docker/.env` file. Find the `RAGFLOW_IMAGE` setting and change the image reference from `infiniflow/ragflow:v0.27.2` to `infiniflow/ragflow:nightly` to use the pre-built image. - - -2. Launch the Service +Set `RAGFLOW_IMAGE=ragflow:go-local` in `docker/.env`. That file also controls the document engine, CPU or GPU selection, ports, and dependency credentials. Change the default passwords before making the service accessible over a network. ```bash cd docker -$ docker compose -f docker-compose-macos.yml up -d +docker compose --env-file .env -f docker-compose.yml up -d ``` -3. Access the RAGFlow Service +The Compose deployment starts the `ragflow-cpu` service. The open-source 1.0 Go DeepDoc backend uses CPU inference. -Once the setup is complete, open your web browser and navigate to http://127.0.0.1 or your server's \; (the default port is \ = 80). You will be directed to the RAGFlow welcome page. Enjoy!🍻 +## Verify the service + +```bash +docker compose --env-file .env -f docker-compose.yml ps +docker compose --env-file .env -f docker-compose.yml logs --tail 50 ragflow-cpu +curl -f http://localhost/api/v1/system/healthz +``` + +A healthy API returns HTTP 200. If you changed `SVR_WEB_HTTP_PORT` in `.env`, use that port in the health-check URL and when opening the web interface in a browser. + +For a development checkout, a database version error may require `RAGFLOW_DEV_MODE=true` in `.env`. Use this only for local development; keep it `false` for production. + +## macOS with Docker Desktop + +The same Go image and Compose file work on macOS. On Apple Silicon, keep `--platform linux/amd64` in the build command so that the x86-64 Go image and native libraries use the same architecture. Emulation can make the build and document processing slower than on an x86-64 Linux host. + +1. Start Docker Desktop and build from the repository root: + + ```bash + git clone https://github.com/infiniflow/ragflow.git + cd ragflow + docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . + ``` + +2. If you use the default Elasticsearch document engine, set `vm.max_map_count` inside Docker Desktop's Linux virtual machine: + + ```bash + docker run --rm --privileged alpine sysctl -w vm.max_map_count=262144 + ``` + + Repeat this command after restarting Docker Desktop. It is unnecessary when using another document engine such as Infinity. + +3. Set `RAGFLOW_IMAGE=ragflow:go-local` in `docker/.env`, then start the Go stack: + + ```bash + cd docker + docker compose --env-file .env -f docker-compose.yml up -d + curl -f http://localhost/api/v1/system/healthz + ``` + + Wait for the health check to return HTTP 200, then open `http://localhost` in a browser. Include `SVR_WEB_HTTP_PORT` in both URLs if you changed its default value. diff --git a/docs/develop/launch_ragflow_from_source.md b/docs/develop/launch_ragflow_from_source.md index 3ff8476b4b..4779490a04 100644 --- a/docs/develop/launch_ragflow_from_source.md +++ b/docs/develop/launch_ragflow_from_source.md @@ -7,160 +7,181 @@ sidebar_custom_props: { categoryIcon: LucideMonitorPlay } --- + # Launch Service from Source -A guide explaining how to set up a RAGFlow service from its source code. By following this guide, you'll be able to debug using the source code. +Build and run the complete Go API, admin, ingestor, and syncer services on your host, with supporting services in Docker. Run all commands from the repository root unless a step says otherwise. This guide uses the default Elasticsearch and MySQL configuration on Ubuntu 24.04 x86_64; the native ONNX Runtime archive used by this build targets Linux x86_64. -## Target Audience +:::note macOS +This source-build procedure is for Ubuntu 24.04 x86_64. On macOS, use Docker Desktop and follow [Build RAGFlow Docker Image](./build_docker_image.mdx) to build and run the Go `linux/amd64` image. +::: -Developers who have added new features or modified existing code and wish to debug using the source code, *provided that* their machine has the target deployment environment set up. +The RAGFlow open-source 1.0 DeepDoc backend uses CPU inference for layout analysis, OCR, and table recognition. + +All long-running RAGFlow processes started below use `bin/ragflow_server`. ## Prerequisites -- CPU ≥ 4 cores -- RAM ≥ 16 GB -- Disk ≥ 50 GB -- Docker ≥ 24.0.0 & Docker Compose ≥ v2.26.1 +- A recommended starting configuration of 4 CPU cores, 16 GB RAM, and 50 GB free disk space. Actual requirements depend on the selected document engine, local models, data volume, parsing workload, and concurrency. +- Docker 24.0.0 or later and Docker Compose v2.26.1 or later. +- Go 1.27 or later, as declared in `go.mod` (check `go version`). +- CMake 4.0 or later, Clang 20, LLD 20, and PCRE2 development headers. +- Node.js 18.20.4 or later and npm for the frontend. +- Python 3.10 or later only for `ragflow_deps/download_go_deps.py`, which downloads the native libraries and model resources required by the Go build. -:::tip NOTE -If you have not installed Docker on your local machine (Windows, Mac, or Linux), see the [Install Docker Engine](https://docs.docker.com/engine/install/) guide. -::: +See the [Docker installation guide](https://docs.docker.com/engine/install/) if Docker is not installed. Use the Go version declared in `go.mod` and the compiler versions listed above when preparing the build environment. -## Launch a Service from Source - -To launch a RAGFlow service from source code: - -### Clone the RAGFlow Repository +## 1. Get the source and build dependencies ```bash git clone https://github.com/infiniflow/ragflow.git -cd ragflow/ +cd ragflow +go version +cmake --version +clang++ --version +ld.lld --version ``` -### Install Python Dependencies - -1. Install uv: - - ```bash - pipx install uv - ``` - -2. Install RAGFlow service's Python dependencies: - - ```bash - uv sync --python 3.13 --frozen - ``` - *A virtual environment named `.venv` is created, and all Python dependencies are installed into the new environment.* - - If you need to run tests against the RAGFlow service, install the test dependencies: - - ```bash - uv sync --python 3.13 --group test --frozen && uv pip install sdk/python --group test - ``` - -:::note macOS -On macOS, some Python dependencies link against native libraries that are not installed by default. Install them with Homebrew before launching the backend service: - - ```bash - brew install unixodbc jemalloc pkg-config - ``` - -- `unixodbc` provides `libodbc.2.dylib`, which the `pyodbc` package links against. Without it, `import pyodbc` fails with `Library not loaded: .../libodbc.2.dylib` (the full path is `$(brew --prefix unixodbc)/lib/libodbc.2.dylib`; `/opt/homebrew` on Apple Silicon, `/usr/local` on Intel), and the ExeSQL agent tool fails to load (look for `Warning: Failed to import module exesql` at startup). -- `jemalloc` and `pkg-config` are required by the preload commands used to launch the task executor; see step 5 of [Launch the RAGFlow Backend Service](#launch-the-ragflow-backend-service). -::: - -### Launch Third-Party Services - -The following command launches the 'base' services (MinIO, Elasticsearch, Redis, and MySQL) using Docker Compose: +Install Go 1.27 or later if needed; make sure the Go executable selected by your shell meets the requirement in `go.mod`. On Ubuntu, install the compiler, linker, PCRE2 headers, Python virtual-environment support, and command-line tools used by the build with: ```bash -docker compose -f docker/docker-compose-base.yml up -d +sudo apt update +sudo apt install -y clang-20 lld-20 libpcre2-dev python3-venv \ + build-essential binutils pkg-config curl ca-certificates ``` -### Update `host` and `port` Settings for Third-Party Services +Ubuntu's enabled repositories may not provide `clang-20` and `lld-20`. If APT cannot locate them, configure the official LLVM APT repository for LLVM 20, then run the installation command again. Follow the repository instructions at [apt.llvm.org](https://apt.llvm.org/) rather than substituting an older LLVM release. -1. Add the following line to `/etc/hosts` to resolve all hosts specified in **docker/service_conf.yaml.template** to `127.0.0.1`: +Make `clang++` resolve to Clang 20 and `ld.lld` to LLD 20 before building. Installing `lld-20` alone does not necessarily replace an older system default `ld.lld`. Check both versions above: an older LLD can produce a binary that builds successfully but fails before the Go server starts. Install CMake 4.0 or later separately if your distribution package is older; the Go development guide includes the Ubuntu 24.04 Kitware repository setup. The `binutils` package supplies `objcopy` and `nm`; do not ignore a missing-`objcopy` warning because skipping the RE2 symbol-renaming step can cause a runtime crash. - ``` - 127.0.0.1 es01 infinity mysql minio redis - ``` +Download the native libraries and Go DeepDoc model weights with a small, isolated Python environment: -2. In **docker/service_conf.yaml.template**, update mysql port to `5455` and es port to `1200`, as specified in **docker/.env**. +```bash +python3 -m venv /tmp/ragflow-go-download-venv +/tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub +/tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_go_deps.py +``` -### Launch the RAGFlow Backend Service +The downloader fetches the static libraries needed by `build.sh`, plus `det.ort`, `layout.ort`, `tsr.ort`, `rec.ort`, and `ocr.res` into `rag/res/deepdoc/`. These files are required by the in-process Go DeepDoc backend. Keep the server's working directory at the repository root so it can find them automatically; if you launch it elsewhere, set `DEEPDOC_MODEL_DIR` to the absolute path of `rag/res/deepdoc`. -1. Comment out the `nginx` line in **docker/entrypoint.sh**. +The isolated download environment can be removed after the resources have been prepared. - ``` - # /usr/sbin/nginx - ``` +Build the C++ bindings and Go binaries: -2. Activate the Python virtual environment: +```bash +bash build.sh --all +``` - ```bash - source .venv/bin/activate - export PYTHONPATH=$(pwd) - ``` +For a smaller production binary, use `bash build.sh --strip --all` instead. The build script also tries to place `ragflow_deps/cl100k_base.tiktoken` in the repository. If it reports that the BPE table could not be provisioned, download it before starting the server: -3. **Optional:** If you cannot access HuggingFace, set the HF_ENDPOINT environment variable to use a mirror site: +```bash +curl -fsSL -o ragflow_deps/cl100k_base.tiktoken https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken +``` - ```bash - export HF_ENDPOINT=https://hf-mirror.com - ``` +Check that the newly built executable can load and parse API arguments: -4. Check the configuration in **conf/service_conf.yaml**, ensuring all hosts and ports are correctly set. +```bash +./bin/ragflow_server --api --help +``` -5. Run the **entrypoint.sh** script to launch the backend service: +It should print API usage information and may exit with status 1. This command only checks that the binary can load and parse arguments; it does not initialize DeepDoc, connect to dependencies, or prove that the API can start. Complete the runtime checks in section 5 after starting the dependencies and Go processes. - ```shell - JEMALLOC_PATH=$(pkg-config --variable=libdir jemalloc)/libjemalloc.so; - LD_PRELOAD=$JEMALLOC_PATH python rag/svr/task_executor.py -i 1; - ``` +The Go/C++ build requires LLD 20. Confirm that `ld.lld --version` reports LLD 20 before building; merely installing `lld-20` is insufficient when an older `ld.lld` remains the system default. If the binary builds successfully but exits or crashes before reaching Go `main`, verify the selected linker and rebuild with LLD 20. - On macOS, use the Homebrew dylib and `DYLD_INSERT_LIBRARIES` instead: +## 2. Start supporting services - ```shell - JEMALLOC_PATH=$(pkg-config --variable=libdir jemalloc)/libjemalloc.2.dylib; - DYLD_INSERT_LIBRARIES=$JEMALLOC_PATH python rag/svr/task_executor.py -i 1; - ``` +With the default `conf/service_conf.yaml`, the host-run Go processes need Elasticsearch, MySQL, MinIO, NATS, Kvrocks, and ClickHouse. Start these services explicitly from the repository root: - ```shell - python api/ragflow_server.py; - ``` +The default Elasticsearch service requires `vm.max_map_count` of at least `262144` on the Docker host. Check and set it before starting the containers: -### Launch the RAGFlow Frontend Service +```bash +sysctl vm.max_map_count +sudo sysctl -w vm.max_map_count=262144 +``` -1. Navigate to the `web` directory and install the frontend dependencies: +The change made with `sysctl -w` is temporary. To preserve it after a reboot, add `vm.max_map_count=262144` to `/etc/sysctl.conf`. - ```bash - cd web - npm install - ``` +```bash +docker compose --env-file docker/.env -f docker/docker-compose-base.yml up -d --wait es01 mysql minio nats kvrocks clickhouse +docker compose --env-file docker/.env -f docker/docker-compose-base.yml ps +``` -2. Start the RAGFlow frontend service with the proxy configured for the Python backend: +The base Compose file also defines an unprofiled Redis service. Starting every service with `up -d` can make Redis and Kvrocks compete for host port 6379; the explicit service list above starts Kvrocks for the Go backend. Compose may print a warning that `REDIS_PORT` is unset because the unused Redis service is still parsed. - ```bash - API_PROXY_SCHEME=python npm run dev - ``` +Check that the services are ready before migrating. For this host-run setup, edit **`conf/service_conf.yaml`** if you changed the published ports or credentials in `docker/.env`. The defaults include MySQL at `localhost:3306`, Elasticsearch at `localhost:1200`, MinIO at `localhost:9000`, Kvrocks at `localhost:6379`, NATS at `localhost:4222`, and ClickHouse at `localhost:9900`. Do not edit `docker/service_conf.yaml.template` for a Go process launched directly on the host, and no `/etc/hosts` entries for Docker service names are needed. - The `python` proxy scheme routes API requests to the Python backend on port `9380`. Use `go` for the Go backend on port `9380`, or `hybrid` when running both backends. +## 3. Migrate and launch the Go backend - *The following message appears, showing the IP address and port number of your frontend service:* +Run the migration once before starting any server process: - ![](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) +```bash +./bin/ragflow_server --migrate +``` -### Access the RAGFlow Service +Then start each Go mode in a separate terminal from the repository root. These four modes are the complete backend service chain. The source-development commands below use `RAGFLOW_DEV_MODE=true` to bypass the code and database version downgrade check; this setting does not run migrations or change the schema. Do not set it in production. Start Admin first so API, Ingestor, and Syncer can report their heartbeats: -In your web browser, enter `http://127.0.0.1:/`, ensuring the port number matches that shown in the screenshot above. +```bash +# Terminal 1: admin (target port 9381) +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin +``` -### Stop the RAGFlow Service When the Development Is Done +```bash +# Terminal 2: API (target port 9380) +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api +``` -1. Stop the RAGFlow frontend service: - ```bash - pkill npm - ``` +```bash +# Terminal 3: document ingestion +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor +``` -2. Stop the RAGFlow backend service: - ```bash - pkill -f "docker/entrypoint.sh" - ``` +Start the Go syncer in another terminal: + +```bash +RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer +``` + +After the migration completes, `RAGFLOW_DEV_MODE=true bash build.sh --run` can be used as a shortcut to start the Go Admin, Ingestor, and API modes. The shortcut does not start Syncer; run the Syncer command above separately when the complete service chain is required. It does not replace the standalone migration step. + +If you changed a dependency's published port or credentials, update `conf/service_conf.yaml` before starting the Go processes. In particular, `kvrocks.host` is a single `host:port` value; the default source configuration is `localhost:6379`. Do not rely on `KVROCKS_HOST` and `KVROCKS_PORT` to override this source configuration. + +`RAGFLOW_DEV_MODE=true` bypasses the code-versus-database version check. Use it only for development, not to run an older production binary against a newer database. The standalone `--migrate` action must still complete first. + +If startup reports `no in-process DeepDoc backend serving`, check that all five model files above are in `rag/res/deepdoc/`, then re-run the Go dependency downloader and rebuild if necessary. If the tokenizer reports a missing `cl100k_base.tiktoken`, ensure the BPE table is in `ragflow_deps/`. + +## 4. Start the frontend + +In another terminal: + +```bash +cd web +npm install +API_PROXY_SCHEME=go npm run dev +``` + +With `API_PROXY_SCHEME=go`, the frontend routes requests to two Go backend ports: regular /api and /v1 requests use port 9380, while /api/v1/admin requests use port 9381. +Open http://127.0.0.1:9222/ unless Vite prints a different frontend port. + +## 5. Verify the startup + +From a separate terminal, check the frontend, an API request through its Go proxy, and the ClickHouse HTTP health endpoint: + +```bash +curl -fsS http://127.0.0.1:9380/api/v1/system/healthz +curl -fsS -o /dev/null -w 'frontend: HTTP %{http_code}\n' http://127.0.0.1:9222/ +curl -fsS http://127.0.0.1:9222/api/v1/system/version +curl -fsS http://127.0.0.1:8123/ping +``` + +The direct Go API health check and frontend should return HTTP 200, the version request should return JSON with `"code":0`, and ClickHouse should respond `Ok.`. These runtime checks confirm that the Go API, frontend proxy, and ClickHouse are reachable; also confirm that the startup logs report the in-process DeepDoc backend as registered before testing your intended RAGFlow workflow. + +## 6. Stop the services + +Press `Ctrl+C` in the frontend and Go server terminals. To stop the dependency containers started in step 2: + +```bash +docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop \ + es01 mysql minio nats kvrocks clickhouse +``` + +`stop` preserves the dependency containers for the next development session. To remove the containers and Compose network while keeping named data volumes, use `docker compose --env-file docker/.env -f docker/docker-compose-base.yml down`. diff --git a/docs/develop/mcp/_category_.json b/docs/develop/mcp/_category_.json index aa67c45a95..09a775a399 100644 --- a/docs/develop/mcp/_category_.json +++ b/docs/develop/mcp/_category_.json @@ -3,7 +3,7 @@ "position": 2, "link": { "type": "generated-index", - "description": "Guides and references on accessing RAGFlow's datasets via MCP." + "description": "Guides for exposing RAGFlow tools through MCP and connecting external MCP servers to RAGFlow." }, "customProps": { "categoryIcon": "SiModelcontextprotocol" diff --git a/docs/develop/mcp/connect_an_external_mcp_to_ragflow.md b/docs/develop/mcp/connect_an_external_mcp_to_ragflow.md index 74ce7fa751..5fca7ee5a6 100644 --- a/docs/develop/mcp/connect_an_external_mcp_to_ragflow.md +++ b/docs/develop/mcp/connect_an_external_mcp_to_ragflow.md @@ -42,15 +42,15 @@ RAGFlow does not directly connect to MCP servers that use `stdio`. To use a `std 3. Open **MCP**. 4. Click **Add MCP**. 5. Configure the MCP server. +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 custom name used to identify the MCP server in RAGFlow | `Local file tools` | -| URL | The complete MCP endpoint | `https://example.com/mcp` | -| Server type | The transport provided by the MCP server | `streamable-http` | -| Description | Optional description of the MCP server | `Read and manage files` | -| Headers | HTTP headers required by the MCP server | `Authorization: Bearer xxx` | -| Variables | Variables required by the MCP server configuration | Depends on the MCP server | +| 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 ` | The server's token | The **Server type** must match the transport exposed by the MCP server: @@ -64,96 +64,54 @@ or: sse ``` -If the MCP server does not require authentication, leave **Headers** empty. +If the MCP server does not require authentication, leave **Authorization Token** empty. The manual form does not expose arbitrary headers, variables, or a description field. For another authentication scheme or custom headers, use a JSON import with a string-to-string `headers` object, as shown in the example below. Make sure that the path in **URL** matches the endpoint actually exposed by the MCP server. For example, a Streamable HTTP server commonly uses `/mcp`, while an SSE server commonly uses `/sse`. -## MCP server URL access restrictions +RAGFlow keeps **Save** disabled until the current connection settings have been tested successfully and at least one tool has been discovered. If you change the URL, server type, or authorization token, test the connection again before saving. -RAGFlow validates MCP server URLs before establishing a connection to protect the RAGFlow backend against server-side request forgery (SSRF) and internal network probing. +## Connection requirements -### Supported URL schemes +RAGFlow validates the endpoint before connecting: -MCP server URLs must use one of the following schemes: +- The URL must use `http://` or `https://` and contain a host. `stdio://` is not supported. +- Every address returned by DNS must be publicly routable. Loopback, private, link-local, reserved, Docker-network, and other non-public addresses are rejected. +- The Go MCP client connects to the validated address directly and does not use HTTP proxy environment variables. -```text -http:// -https:// +Consequently, endpoints such as `localhost`, `127.0.0.1`, `::1`, `10.x.x.x`, `172.16.x.x` through `172.31.x.x`, and `192.168.x.x` cannot be added through this path. `ALLOW_ANY_HOST` does not disable this validation. Publish the MCP endpoint on a public address whose DNS records all resolve to public addresses. + +## 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. | + +## Example: add Parallel Search MCP tools + +[Parallel Search MCP](https://docs.parallel.ai/integrations/mcp/search-mcp) provides `web_search` and `web_fetch` tools. Save the repository's [example configuration](https://github.com/infiniflow/ragflow/blob/main/example/mcp/parallel_search.json) as a JSON file: + +```json +{ + "mcpServers": { + "parallel-search": { + "type": "streamable-http", + "url": "https://search.parallel.ai/mcp", + "headers": { + "User-Agent": "ragflow" + } + } + } +} ``` -The URL must contain a valid hostname or IP address. +Open **User settings → MCP** and import the file. RAGFlow discovers the server's tools during import. The example has no authorization token. If you enter the connection manually, select **Streamable HTTP** and leave **Authorization Token** empty. -Other URL schemes, including `stdio://`, are not supported for MCP server connections. +In an **Agent** component, add the imported tools from `parallel-search` and enable `web_search` or `web_fetch` as needed. Importing a server does not automatically make its tools the agent's default search tool. -### Public address validation +Check that discovery returns both tool names. Then inspect an agent run's tool calls to confirm it selected one. If connection fails, check the transport, outbound access to `search.parallel.ai`, and configured headers. Queries, requested URLs, and request context sent through these tools reach Parallel; review its [privacy policy](https://parallel.ai/privacy-policy) before sending sensitive content. -By default, RAGFlow allows an MCP server URL only when **all IP addresses resolved from its hostname are publicly routable addresses**. - -With the default configuration: - -```text -ALLOW_ANY_HOST=0 -``` - -RAGFlow rejects URLs that resolve to loopback, private, link-local, reserved, or other non-public addresses. - -Examples of addresses that are rejected by default include: - -```text -127.0.0.1 -::1 -10.x.x.x -172.16.x.x - 172.31.x.x -192.168.x.x -``` - -This also affects hostnames. Even if the URL uses a public domain name, RAGFlow rejects the connection if that domain resolves to a non-public IP address in the environment where the RAGFlow backend is running. - -For example: - -```text -https://mcp.example.com/mcp -``` - -can still be rejected if `mcp.example.com` resolves to a private, loopback, or synthetic address. - -### Fake-IP DNS results - -Proxy applications such as Mihomo or Clash may use Fake-IP mode and return synthetic addresses for public domains. - -For example, a public domain may resolve to an address in a range such as: - -```text -fdfe:dcba:9876::/48 -``` - -RAGFlow identifies such addresses as non-public and may display an error similar to: - -```text -URL resolves to a non-public address (...), which is not allowed. -``` - -If you see this error, check DNS resolution from the environment where the RAGFlow backend is running. - -The error does not necessarily indicate that the MCP server URL, transport type, or authentication configuration is incorrect. - -## Connect to a local or private MCP server - -For trusted local development or testing environments, you can allow RAGFlow to connect to MCP servers running on localhost, a private network, or a Docker network. - -In `docker/.env`, set: - -```text -ALLOW_ANY_HOST=1 -``` - -Then fully restart the RAGFlow backend services so that the new environment setting takes effect. - -For example: - -```bash -docker compose down -docker compose up -d -``` - -When `ALLOW_ANY_HOST=1`, RAGFlow skips the public-address validation described above. +For other MCP servers, use their documented URL, transport, and authentication. Imported `headers` must be an object with string names and string values. Keep real credentials out of committed configuration files. diff --git a/docs/develop/mcp/connect_external_mcp_servers.md b/docs/develop/mcp/connect_external_mcp_servers.md index 447cbd1d14..b08b4ad531 100644 --- a/docs/develop/mcp/connect_external_mcp_servers.md +++ b/docs/develop/mcp/connect_external_mcp_servers.md @@ -1,48 +1,13 @@ --- -sidebar_position: 4 -title: Connect external MCP tools -sidebar_label: Connect external MCP tools +title: Connect an External MCP Server to RAGFlow slug: /connect_external_mcp_servers -sidebar_custom_props: { - categoryIcon: LucideBookMarked -} +unlisted: true --- -# Connect external MCP tools -RAGFlow agents can use an external MCP server alongside their existing tools. This is different from [running RAGFlow's MCP server](./launch_mcp_server.md), which exposes your RAGFlow resources to other clients. +import {Redirect} from '@docusaurus/router'; -## Add web research with Parallel + -[Parallel Search MCP](https://docs.parallel.ai/integrations/mcp/search-mcp) provides `web_search` for finding web sources and `web_fetch` for reading known public URLs. Its anonymous endpoint does not require a Parallel account or API key. Free access is rate limited. +# Page moved -1. Save the [example configuration](https://github.com/infiniflow/ragflow/blob/main/example/mcp/parallel_search.json) as a JSON file: - - ```json - { - "mcpServers": { - "parallel-search": { - "type": "streamable-http", - "url": "https://search.parallel.ai/mcp", - "headers": { - "User-Agent": "ragflow" - } - } - } - } - ``` - -2. Open **Settings → MCP** and import the file. RAGFlow connects to the server and discovers its tools. Use **Streamable HTTP**, not SSE, if entering the connection manually. Leave the Parallel authorization token empty. -3. In an **Agent** component, add the MCP tools from `parallel-search` and enable `web_search` and `web_fetch` as needed. Importing the server does not replace an existing search tool or make Parallel the default. -4. Try a public-web question such as: “Find RAGFlow's current release notes and summarize the latest changes with source links.” The agent can search, then fetch a relevant result. No private dataset is needed for this example. - -The `User-Agent` identifies RAGFlow so Parallel can measure aggregate usage by project. Keep it project-wide; do not add a user, installation or device identifier. Imported headers are used during discovery and subsequent tool calls and are retained when exporting the server configuration. - -When enabled, the agent may call these tools during its normal workflow. Supplied search queries, requested URLs, objectives/context and request metadata go to Parallel. Review its [privacy policy](https://parallel.ai/privacy-policy) before sending sensitive content. Anonymous Parallel access does not remove authentication required by your RAGFlow installation. - -## Check a connection - -Confirm that tool discovery returns `web_search` and `web_fetch`. A successful connection alone does not prove that the agent selected a tool; inspect the agent run's tool calls and returned source links. - -For connection errors, check the transport, outbound access to `search.parallel.ai`, and the configured headers. The free example deliberately omits authentication headers. If you configured an authenticated connection, investigate its credentials instead of silently removing them. Respect rate-limit responses and avoid repeated immediate retries. - -For other MCP servers, use their documented URL, transport and authentication. Custom `headers` must be an object with string names and string values. Never commit real credentials in an exported configuration. +External MCP setup and the Parallel Search example are now in [Connect an External MCP Server to RAGFlow](./connect_an_external_mcp_to_ragflow.md). diff --git a/docs/develop/mcp/launch_mcp_server.md b/docs/develop/mcp/launch_mcp_server.md index 15ca0f1891..416cfa820a 100644 --- a/docs/develop/mcp/launch_mcp_server.md +++ b/docs/develop/mcp/launch_mcp_server.md @@ -1,216 +1,13 @@ --- -sidebar_position: 11 -title: Launch RAGFlow MCP Server -sidebar_label: Launch RAGFlow MCP Server +title: Use RAGFlow as an MCP Server slug: /launch_mcp_server -sidebar_custom_props: { - categoryIcon: LucideTvMinimalPlay -} ---- -# Launch RAGFlow MCP Server - -Launch an MCP server from source or via Docker. - +unlisted: true --- -A RAGFlow Model Context Protocol (MCP) server is designed as an independent component to complement the RAGFlow server. Note that an MCP server must operate alongside a properly functioning RAGFlow server. +import {Redirect} from '@docusaurus/router'; -An MCP server can start up in either self-host mode (default) or host mode: + -- **Self-host mode**: - When launching an MCP server in self-host mode, you must provide an API key to authenticate the MCP server with the RAGFlow server. In this mode, the MCP server can access *only* the datasets of a specified tenant on the RAGFlow server. -- **Host mode**: - In host mode, each MCP client can access their own datasets on the RAGFlow server. However, each client request must include a valid API key to authenticate the client with the RAGFlow server. +# Page moved -Once a connection is established, an MCP server communicates with its client in MCP HTTP+SSE (Server-Sent Events) mode, unidirectionally pushing responses from the RAGFlow server to its client in real time. - -## Prerequisites - -1. Ensure RAGFlow is upgraded to v0.18.0 or later. -2. Have your RAGFlow API key ready. See [Acquire a RAGFlow API key](../acquire_ragflow_api_key.md). - -:::tip INFO -If you wish to try out our MCP server without upgrading RAGFlow, community contributor [yiminghub2024](https://github.com/yiminghub2024) 👏 shares their recommended steps [here](#launch-an-mcp-server-without-upgrading-ragflow). -::: - -## Launch an MCP Server - -You can start an MCP server either from source code or via Docker. - -### Launch from Source Code - -1. Ensure that a RAGFlow server v0.18.0+ is properly running. -2. Launch the MCP server: - - -```bash -# Launch the MCP server to work in self-host mode, run either of the following -uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --api-key=ragflow-xxxxx -# uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --mode=self-host --api-key=ragflow-xxxxx - -# To launch the MCP server to work in host mode, run the following instead: -# uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --mode=host -``` - -Where: - -- `host`: The MCP server's host address. -- `port`: The MCP server's listening port. -- `base_url`: The address of the running RAGFlow server. -- `mode`: The launch mode. - - `self-host`: (default) self-host mode. - - `host`: host mode. -- `api_key`: Required in self-host mode to authenticate the MCP server with the RAGFlow server. See [here](../acquire_ragflow_api_key.md) for instructions on acquiring an API key. - -### Transports - -The RAGFlow MCP server supports two transports: the legacy SSE transport (served at `/sse`), introduced on November 5, 2024, and deprecated on March 26, 2025, and the streamable-HTTP transport (served at `/mcp`). The legacy SSE transport and the streamable HTTP transport with JSON responses are enabled by default. To disable either transport, use the flags `--no-transport-sse-enabled` or `--no-transport-streamable-http-enabled`. To disable JSON responses for the streamable HTTP transport, use the `--no-json-response` flag. - -### Launch from Docker - -#### 1. Enable MCP Server - -The MCP server is designed as an optional component that complements the RAGFlow server and disabled by default. To enable MCP server: - -1. Navigate to **docker/docker-compose.yml**. -2. Uncomment the `services.ragflow.command` section as shown below: - -```yaml {6-13} - services: - ragflow: - ... - image: ${RAGFLOW_IMAGE} - # Example configuration to set up an MCP server: - command: - - --enable-mcpserver - - --mcp-host=0.0.0.0 - - --mcp-port=9382 - - --mcp-base-url=http://127.0.0.1:9380 - - --mcp-script-path=/ragflow/mcp/server/server.py - - --mcp-mode=self-host - - --mcp-host-api-key=ragflow-xxxxxxx - # Optional transport flags for the RAGFlow MCP server. - # If you set `mcp-mode` to `host`, you must add the --no-transport-streamable-http-enabled flag, because the streamable-HTTP transport is not yet supported in host mode. - # The legacy SSE transport and the streamable-HTTP transport with JSON responses are enabled by default. - # To disable a specific transport or JSON responses for the streamable-HTTP transport, use the corresponding flag(s): - # - --no-transport-sse-enabled # Disables the legacy SSE endpoint (/sse) - # - --no-transport-streamable-http-enabled # Disables the streamable-HTTP transport (served at the /mcp endpoint) - # - --no-json-response # Disables JSON responses for the streamable-HTTP transport -``` - -Where: - -- `mcp-host`: The MCP server's host address. -- `mcp-port`: The MCP server's listening port. -- `mcp-base-url`: The address of the running RAGFlow server. -- `mcp-script-path`: The file path to the MCP server’s main script. -- `mcp-mode`: The launch mode. - - `self-host`: (default) self-host mode. - - `host`: host mode. -- `mcp-host-api_key`: Required in self-host mode to authenticate the MCP server with the RAGFlow server. See [here](../acquire_ragflow_api_key.md) for instructions on acquiring an API key. - -:::tip INFO -If you set `mcp-mode` to `host`, you must add the `--no-transport-streamable-http-enabled` flag, because the streamable-HTTP transport is not yet supported in host mode. -::: - -#### 2. Launch a RAGFlow Server with an MCP Server - -Run `docker compose -f docker-compose.yml up` to launch the RAGFlow server together with the MCP server. - -*The following ASCII art confirms a successful launch:* - -```bash - docker-ragflow-cpu-1 | Starting MCP Server on 0.0.0.0:9382 with base URL http://127.0.0.1:9380... - docker-ragflow-cpu-1 | Starting 1 task executor(s) on host 'dd0b5e07e76f'... - docker-ragflow-cpu-1 | 2025-04-18 15:41:18,816 INFO 27 ragflow_server log path: /ragflow/logs/ragflow_server.log, log levels: {'peewee': 'WARNING', 'pdfminer': 'WARNING', 'root': 'INFO'} - docker-ragflow-cpu-1 | - docker-ragflow-cpu-1 | __ __ ____ ____ ____ _____ ______ _______ ____ - docker-ragflow-cpu-1 | | \/ |/ ___| _ \ / ___|| ____| _ \ \ / / ____| _ \ - docker-ragflow-cpu-1 | | |\/| | | | |_) | \___ \| _| | |_) \ \ / /| _| | |_) | - docker-ragflow-cpu-1 | | | | | |___| __/ ___) | |___| _ < \ V / | |___| _ < - docker-ragflow-cpu-1 | |_| |_|\____|_| |____/|_____|_| \_\ \_/ |_____|_| \_\ - docker-ragflow-cpu-1 | - docker-ragflow-cpu-1 | MCP launch mode: self-host - docker-ragflow-cpu-1 | MCP host: 0.0.0.0 - docker-ragflow-cpu-1 | MCP port: 9382 - docker-ragflow-cpu-1 | MCP base_url: http://127.0.0.1:9380 - docker-ragflow-cpu-1 | INFO: Started server process [26] - docker-ragflow-cpu-1 | INFO: Waiting for application startup. - docker-ragflow-cpu-1 | INFO: Application startup complete. - docker-ragflow-cpu-1 | INFO: Uvicorn running on http://0.0.0.0:9382 (Press CTRL+C to quit) - docker-ragflow-cpu-1 | 2025-04-18 15:41:20,469 INFO 27 found 0 gpus - docker-ragflow-cpu-1 | 2025-04-18 15:41:23,263 INFO 27 init database on cluster mode successfully - docker-ragflow-cpu-1 | 2025-04-18 15:41:25,318 INFO 27 load_model /ragflow/rag/res/deepdoc/det.onnx uses CPU - docker-ragflow-cpu-1 | 2025-04-18 15:41:25,367 INFO 27 load_model /ragflow/rag/res/deepdoc/rec.onnx uses CPU - docker-ragflow-cpu-1 | ____ ___ ______ ______ __ - docker-ragflow-cpu-1 | / __ \ / | / ____// ____// /____ _ __ - docker-ragflow-cpu-1 | / /_/ // /| | / / __ / /_ / // __ \| | /| / / - docker-ragflow-cpu-1 | / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - docker-ragflow-cpu-1 | /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - docker-ragflow-cpu-1 | - docker-ragflow-cpu-1 | - docker-ragflow-cpu-1 | 2025-04-18 15:41:29,088 INFO 27 RAGFlow version: v0.18.0-285-gb2c299fa full - docker-ragflow-cpu-1 | 2025-04-18 15:41:29,088 INFO 27 project base: /ragflow - docker-ragflow-cpu-1 | 2025-04-18 15:41:29,088 INFO 27 Current configs, from /ragflow/conf/service_conf.yaml: - docker-ragflow-cpu-1 | ragflow: {'host': '0.0.0.0', 'http_port': 9380} - ... - docker-ragflow-cpu-1 | * Running on all addresses (0.0.0.0) - docker-ragflow-cpu-1 | * Running on http://127.0.0.1:9380 - docker-ragflow-cpu-1 | * Running on http://172.19.0.6:9380 - docker-ragflow-cpu-1 | ______ __ ______ __ - docker-ragflow-cpu-1 | /_ __/___ ______/ /__ / ____/ _____ _______ __/ /_____ _____ - docker-ragflow-cpu-1 | / / / __ `/ ___/ //_/ / __/ | |/_/ _ \/ ___/ / / / __/ __ \/ ___/ - docker-ragflow-cpu-1 | / / / /_/ (__ ) ,< / /____> `. ------- +## Python client -## Example MCP Python Client +This example targets version 2 of the MCP Python SDK, which requires Python 3.10 or later: -We provide a *prototype* MCP client example for testing [here](https://github.com/infiniflow/ragflow/blob/main/mcp/client/client.py). +```bash +python -m pip install 'mcp>=2,<3' +``` -:::info IMPORTANT -If your MCP server is running in host mode, include your acquired API key in your client's `headers` when connecting asynchronously to it: +The current SDK uses `streamable_http_client`. HTTP headers belong on an `httpx2.AsyncClient` passed to that transport: ```python -async with sse_client("http://localhost:9382/sse", headers={"api_key": "YOUR_KEY_HERE"}) as streams: - # Rest of your code... +import asyncio + +import httpx2 +from mcp import Client +from mcp.client.streamable_http import streamable_http_client + + +async def main() -> None: + async with httpx2.AsyncClient( + headers={"Authorization": "Bearer "}, + timeout=httpx2.Timeout(30.0, read=300.0), + ) as http_client: + transport = streamable_http_client( + "http://127.0.0.1:9380/api/v1/mcp", + http_client=http_client, + ) + async with Client(transport) as client: + tools = await client.list_tools() + print([tool.name for tool in tools.tools]) + + result = await client.call_tool( + "ragflow_retrieval", + {"question": "How do I install Neovim?"}, + ) + print(result.content) + + +asyncio.run(main()) ``` -Alternatively, to comply with [OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5), you can run the following code *instead* to connect to your MCP server: +Entering the `Client` context negotiates the supported MCP protocol automatically. The Go server currently supports `2025-11-25`, `2025-06-18`, `2025-03-26`, and `2024-11-05`. -```python -async with sse_client("http://localhost:9382/sse", headers={"Authorization": "YOUR_KEY_HERE"}) as streams: - # Rest of your code... -``` -::: +## curl smoke checks -## Use Curl to Interact with the RAGFlow MCP Server +The Go Streamable HTTP handler is stateless: each POST uses a temporary MCP session with default initialization parameters. The following commands are therefore **independent smoke checks**. The initialization request demonstrates protocol negotiation; it does not create a reusable session for the later commands. -When interacting with the MCP server via HTTP requests, follow this initialization sequence: - -1. **The client sends an `initialize` request** with protocol version and capabilities. -2. **The server replies with an `initialize` response**, including the supported protocol and capabilities. -3. **The client confirms readiness with an `initialized` notification**. - _The connection is established between the client and the server, and further operations (such as tool listing) may proceed._ - -:::tip NOTE -For more information about this initialization process, see [here](https://modelcontextprotocol.io/docs/concepts/architecture#1-initialization). -::: - -In the following sections, we will walk you through a complete tool calling process. - -### 1. Obtain a Session ID - -Each curl request with the MCP server must include a session ID: +### Initialize ```bash -$ curl -N -H "api_key: YOUR_API_KEY" http://127.0.0.1:9382/sse +curl -sS http://127.0.0.1:9380/api/v1/mcp \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' ``` -:::tip NOTE -See [here](../acquire_ragflow_api_key.md) for information about acquiring an API key. -::: +A successful response contains `result.serverInfo.name` set to `ragflow-mcp-server` and a negotiated `protocolVersion`. -#### Transport - -The transport will stream messages such as tool results, server responses, and keep-alive pings. - -_The server returns the session ID:_ +### List tools ```bash -event: endpoint -data: /messages/?session_id=5c6600ef61b845a788ddf30dceb25c54 +curl -sS http://127.0.0.1:9380/api/v1/mcp \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' ``` -### 2. Send an `Initialize` Request +The response lists `ragflow_retrieval`, `ragflow_list_datasets`, and `ragflow_list_chats`. A normal MCP SDK client performs initialization and sends the initialized notification automatically; raw stateless smoke checks do not need to reuse that state. -The client sends an `initialize` request with protocol version and capabilities: +### Call a tool ```bash -session_id="5c6600ef61b845a788ddf30dceb25c54" && \ - -curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \ - -H "api_key: YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": 1, - "method": "initialize", - "params": { - "protocolVersion": "1.0", - "capabilities": {}, - "clientInfo": { - "name": "ragflow-mcp-client", - "version": "0.1" - } - } - }' && \ +curl -sS http://127.0.0.1:9380/api/v1/mcp \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ragflow_retrieval","arguments":{"question":"How do I install Neovim?"}}}' ``` -#### Transport +The MCP result contains a text content item whose text is the JSON retrieval result. Add `dataset_ids` or other supported arguments under `arguments` when needed. See [RAGFlow MCP Tools](./mcp_tools.md) for the complete schemas. -_The server replies with an `initialize` response, including the supported protocol and capabilities:_ +## Legacy SSE clients -```bash -event: message -data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"experimental":{"headers":{"host":"127.0.0.1:9382","user-agent":"curl/8.7.1","accept":"*/*","api_key":"ragflow-xxxxxxxxxxxx","accept-encoding":"gzip"}},"tools":{"listChanged":false}},"serverInfo":{"name":"docker-ragflow-cpu-1","version":"1.9.4"}}} -``` - -### 3. Acknowledge Readiness - -The client confirms readiness with an `initialized` notification: - -```bash -curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \ - -H "api_key: YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "method": "notifications/initialized", - "params": {} - }' && \ -``` - - _The connection is established between the client and the server, and further operations (such as tool listing) may proceed._ - -### 4. Tool Listing - -```bash -curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \ - -H "api_key: YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": 3, - "method": "tools/list", - "params": {} - }' && \ -``` - -#### Transport - -```bash -event: message -data: {"jsonrpc":"2.0","id":3,"result":{"tools":[{"name":"ragflow_retrieval","description":"Retrieve relevant chunks from the RAGFlow retrieve interface based on the question, using the specified dataset_ids and optionally document_ids. Below is the list of all available datasets, including their descriptions and IDs. If you're unsure which datasets are relevant to the question, simply pass all dataset IDs to the function.","inputSchema":{"type":"object","properties":{"dataset_ids":{"type":"array","items":{"type":"string"}},"document_ids":{"type":"array","items":{"type":"string"}},"question":{"type":"string"}},"required":["dataset_ids","question"]}}]}} - -``` - -### 5. Tool Calling - -```bash -curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \ - -H "api_key: YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": 4, - "method": "tools/call", - "params": { - "name": "ragflow_retrieval", - "arguments": { - "question": "How to install neovim?", - "dataset_ids": ["DATASET_ID_HERE"], - "document_ids": [] - } - } - }' -``` - -#### Transport - -```bash -event: message -data: {"jsonrpc":"2.0","id":4,"result":{...}} - -``` - -### A Complete Curl Example - -```bash -session_id="YOUR_SESSION_ID" && \ - -# Step 1: Initialize request -curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \ - -H "api_key: YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": 1, - "method": "initialize", - "params": { - "protocolVersion": "1.0", - "capabilities": {}, - "clientInfo": { - "name": "ragflow-mcp-client", - "version": "0.1" - } - } - }' && \ - -sleep 2 && \ - -# Step 2: Initialized notification -curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \ - -H "api_key: YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "method": "notifications/initialized", - "params": {} - }' && \ - -sleep 2 && \ - -# Step 3: Tool listing -curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \ - -H "api_key: YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": 3, - "method": "tools/list", - "params": {} - }' && \ - -sleep 2 && \ - -# Step 4: Tool call -curl -X POST "http://127.0.0.1:9382/messages/?session_id=$session_id" \ - -H "api_key: YOUR_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": 4, - "method": "tools/call", - "params": { - "name": "ragflow_retrieval", - "arguments": { - "question": "How to install neovim?", - "dataset_ids": ["DATASET_ID_HERE"], - "document_ids": [] - } - } - }' - -``` +The built-in `/api/v1/mcp` route does not provide SSE. When SSE is enabled on the optional listener, legacy clients connect to `http://127.0.0.1:9382/sse`; the server provides the corresponding `/messages/` URL. Use an MCP SDK to manage the SSE session and include the same authentication header on both requests. diff --git a/docs/develop/mcp/mcp_tools.md b/docs/develop/mcp/mcp_tools.md index 3dc87b8e45..dc23ebcac0 100644 --- a/docs/develop/mcp/mcp_tools.md +++ b/docs/develop/mcp/mcp_tools.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 4 title: RAGFlow MCP Tools sidebar_label: RAGFlow MCP Tools slug: /mcp_tools @@ -7,10 +7,61 @@ sidebar_custom_props: { categoryIcon: LucideToolCase } --- + # RAGFlow MCP Tools -The MCP server currently offers a specialized tool to assist users in searching for relevant information powered by RAGFlow DeepDoc technology: +The Go MCP runtime registers three tools. Calls run as the user selected by the endpoint's authentication mode and have a 60-second server-side timeout. -- **retrieve**: Fetches relevant chunks from specified `dataset_ids` and optional `document_ids` using the RAGFlow retrieve interface, based on a given question. Details of all available datasets, namely, `id` and `description`, are provided within the tool description for each individual dataset. +## `ragflow_retrieval` -For more information, see our Python implementation of the [MCP server](https://github.com/infiniflow/ragflow/blob/main/mcp/server/server.py). +Retrieves relevant chunks from datasets available to the authenticated user. When `dataset_ids` is omitted or empty, RAGFlow searches all datasets that user can access. + +| Argument | Type | Required | Default | Valid values and behavior | +| --- | --- | --- | --- | --- | +| `question` | string | Yes | — | Query used for retrieval. | +| `dataset_ids` | array of strings | No | All accessible datasets | Limits retrieval to the specified datasets. | +| `document_ids` | array of strings | No | All documents in the selected datasets | Limits retrieval to the specified documents. | +| `page` | integer | No | `1` | Minimum `1`. | +| `page_size` | integer | No | `10` | From `1` through `100`; `50` or fewer is recommended to limit response size. | +| `similarity_threshold` | number | No | `0.2` | From `0.0` through `1.0`. | +| `vector_similarity_weight` | number | No | `0.3` | From `0.0` through `1.0`; controls the vector-similarity contribution relative to term similarity. | +| `keyword` | boolean | No | `false` | Enables keyword-based search when true. | +| `top_k` | integer | No | `1024` | From `1` through `1024`; maximum candidate count considered before ranking. | +| `rerank_id` | string | No | Empty | Optional reranking model ID. | +| `force_refresh` | boolean | No | `false` | Passes a metadata refresh request to the retrieval service. | + +`page × page_size` must not exceed the fixed window of 512 rerank candidates. Requests beyond that window return an error. + +The tool returns one text content item. Its text is a JSON object with: + +- `chunks`: the retrieved chunks, supplemented with dataset names, document names, and available document metadata. +- `pagination`: `page`, `page_size`, `total_chunks`, and `total_pages`. +- `query_info`: the question, similarity threshold, vector weight, keyword-search setting, and number of searched datasets. + +## `ragflow_list_datasets` + +Lists datasets available to the authenticated user in descending creation-time order. + +| Argument | Type | Required | Default | Valid values and behavior | +| --- | --- | --- | --- | --- | +| `page` | integer | No | `1` | Minimum `1`. | +| `page_size` | integer | No | `100` | From `1` through `100`; a single call returns at most 100 datasets. | + +The tool returns one text content item containing one JSON object per line. Each object contains `id`, `name`, and `description`. The text is empty when no datasets are available. + +## `ragflow_list_chats` + +Lists chat assistants available to the authenticated user in descending creation-time order. + +| Argument | Type | Required | Default | Valid values and behavior | +| --- | --- | --- | --- | --- | +| `page` | integer | No | `1` | Minimum `1`. | +| `page_size` | integer | No | `30` | From `1` through `100`. | + +The tool returns one text content item containing one JSON object per line. Each object contains `id`, `name`, and `description`. The text is empty when no chat assistants are available. + +## Tool discovery + +`tools/list` returns the schemas above. RAGFlow also appends the authenticated user's accessible dataset information to the retrieval and dataset-listing descriptions, and accessible chat information to the chat-listing description. + +For the authoritative implementation, see the [Go tool schemas](https://github.com/infiniflow/ragflow/blob/main/internal/mcp/tools.json), [tool registration](https://github.com/infiniflow/ragflow/blob/main/internal/mcp/server.go), [service connector](https://github.com/infiniflow/ragflow/blob/main/internal/mcp/connector.go), [MCP protocol handler](https://github.com/infiniflow/ragflow/blob/main/internal/handler/mcp_server.go), and [retrieval result handler](https://github.com/infiniflow/ragflow/blob/main/internal/handler/mcp_retrieval.go). diff --git a/docs/develop/mcp/native_go_mcp.md b/docs/develop/mcp/native_go_mcp.md index d36cfd0d3c..9a06d8b687 100644 --- a/docs/develop/mcp/native_go_mcp.md +++ b/docs/develop/mcp/native_go_mcp.md @@ -1,95 +1,13 @@ --- -sidebar_position: 4 -title: Native Go MCP Runtime -sidebar_label: Native Go MCP Runtime +title: Use RAGFlow as an MCP Server slug: /native_go_mcp -sidebar_custom_props: { - categoryIcon: SiModelcontextprotocol -} +unlisted: true --- -# Native Go MCP Runtime -The Go API server can host RAGFlow's MCP runtime in-process. It does not launch `mcp/server/server.py` and does not need a RAGFlow base URL because MCP tool calls use Go services directly. +import {Redirect} from '@docusaurus/router'; -## Configuration + -The Go API process owns the optional standalone MCP listener. Configure it in the -existing `service_conf.yaml` (selected with `--config`), or use environment -variables. MCP settings are no longer command-line flags in either -`ragflow_server` or `entrypoint-go.sh`; replace those flags with the settings below. -Mode selection, help, version and configuration-file selection remain CLI options. +# Page moved -This example enables the listener for clients that each supply their own credential: - -```yaml -mcp: - enabled: true - host: 127.0.0.1 - port: 9382 - launch_mode: host - transport_sse_enabled: true - transport_streamable_enabled: true - json_response: true -``` - -Start the binary with `bin/ragflow_server --api --config conf/service_conf.yaml`. -Uncomment the MCP example in `conf/service_conf.yaml` for a local binary, or in -`docker/service_conf.yaml.template` for Docker. The Docker entrypoint generates -`service_conf.yaml` from that template on startup, so edit the template rather -than the generated file. Alternatively, put the environment settings in -`docker/.env-go`. Start `entrypoint-go.sh` without MCP flags. -For access through a published Docker port, set the container bind address to -`0.0.0.0` and publish `9382`; use host mode for clients outside a trusted network. -The existing MCP endpoint on the main API remains available independently. - -Environment values override YAML, which overrides built-in defaults: - -| Environment variable | YAML field under `mcp` | Default | -| --- | --- | --- | -| `RAGFLOW_MCP_ENABLED` | `enabled` | `false` | -| `RAGFLOW_MCP_HOST` | `host` | `127.0.0.1` | -| `RAGFLOW_MCP_PORT` | `port` | `9382` | -| `RAGFLOW_MCP_LAUNCH_MODE` | `launch_mode` | `self-host` | -| `RAGFLOW_MCP_HOST_API_KEY` | `host_api_key` | empty | -| `RAGFLOW_MCP_TRANSPORT_SSE_ENABLED` | `transport_sse_enabled` | `true` | -| `RAGFLOW_MCP_TRANSPORT_STREAMABLE_ENABLED` | `transport_streamable_enabled` | `true` | -| `RAGFLOW_MCP_JSON_RESPONSE` | `json_response` | `true` | - -Boolean values `1`, `true`, `yes` and `on` are true (case-insensitive, surrounding -whitespace ignored); other values are false. Explicitly empty environment values -override YAML too. An empty host binds all interfaces; use `127.0.0.1` to restrict -access to the local machine. Invalid ports or launch modes reject startup. - -## Authentication - -Host mode resolves each request independently. Clients may supply -`Authorization: Bearer `, `api_key`, `X-API-Key`, or `Api-Key`. - -Self-host mode intentionally gives **every connected client the configured user's -identity**, ignoring client credentials. It is for a trusted local deployment or -an access-controlled network. Enabling it requires `RAGFLOW_MCP_HOST_API_KEY` or -`mcp.host_api_key`. The key is checked at startup and on every request, so revocation -still takes effect. Keep secrets in the deployment environment, out of command -arguments and committed files. The key is omitted from configuration logs. - -## Transports - -Both SSE (`/sse` and `/messages/`) and streamable HTTP (`/mcp`) are enabled by -default. Set `transport_sse_enabled` or `transport_streamable_enabled` to `false` -to disable one. Set `json_response: false` to stream streamable HTTP responses. - -If streamable HTTP is disabled, JSON responses are disabled first. If both -transports are disabled, streamable HTTP is then re-enabled with JSON responses -still disabled, preserving the Python server's resolution order. - -## Streamable HTTP smoke example - -```bash -curl -sS http://127.0.0.1:9382/mcp \ - -H 'Content-Type: application/json' \ - -H 'Accept: application/json, text/event-stream' \ - -H 'Authorization: Bearer ragflow-xxxxx' \ - -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' -``` - -Then send the `notifications/initialized` notification before `tools/list` or `tools/call` when using a real MCP client. +The native Go MCP runtime documentation is now part of [Use RAGFlow as an MCP Server](./use_ragflow_as_mcp_server.md). diff --git a/docs/develop/mcp/overview.md b/docs/develop/mcp/overview.md index 986dfb6cec..dc7cb4c1c3 100644 --- a/docs/develop/mcp/overview.md +++ b/docs/develop/mcp/overview.md @@ -9,68 +9,35 @@ sidebar_custom_props: # MCP Overview -## What is MCP? +Model Context Protocol (MCP) lets AI applications discover and call tools exposed by an MCP server. RAGFlow supports both sides of this integration: -Model Context Protocol (MCP) is an open protocol for connecting AI applications with external tools, data sources, and services. +| Goal | RAGFlow's role | Start here | +| --- | --- | --- | +| Call RAGFlow retrieval, dataset, and chat-listing tools from another application | MCP server | [Use RAGFlow as an MCP Server](./use_ragflow_as_mcp_server.md) | +| Use tools from another system in a RAGFlow Agent | MCP client | [Connect an External MCP Server to RAGFlow](./connect_an_external_mcp_to_ragflow.md) | -Through MCP, an MCP client can discover and invoke tools provided by an MCP server. RAGFlow can either act as an MCP server to expose its capabilities to external clients or connect to external MCP servers to extend the tools available to RAGFlow Agents. +## Use RAGFlow as an MCP server -## MCP usage scenarios in RAGFlow - -RAGFlow currently supports the following two MCP usage scenarios. - -### Use RAGFlow as an MCP server - -RAGFlow can act as an MCP server and expose capabilities such as knowledge base retrieval to external MCP clients. - -The RAGFlow MCP server runs as a standalone component alongside a properly functioning RAGFlow server. - -The MCP server supports two launch modes: - -* **Self-host mode**: Provide a RAGFlow API key when starting the MCP server. The MCP server uses this API key to access RAGFlow resources available to the corresponding user. -* **Host mode**: The MCP server is not bound to a fixed user. Each MCP client provides its own authentication information in requests and can access only the RAGFlow resources available to that user. - -The RAGFlow MCP server supports the following transports: - -* **Streamable HTTP**: Communicates through the `/mcp` endpoint. -* **SSE**: Communicates through the `/sse` and `/messages/` endpoints and is retained for compatibility with legacy MCP clients. - -A typical request flow is: +The Go API server exposes RAGFlow tools directly at its built-in MCP endpoint. ```text -External MCP Client +External MCP client + ↓ MCP request +Go API server: /api/v1/mcp or optional MCP listener ↓ -RAGFlow MCP Server - ↓ -RAGFlow Server - ↓ -RAGFlow capabilities +RAGFlow services (datasets, chats, retrieval) ``` -For information about starting and configuring the RAGFlow MCP server, see **Launch RAGFlow MCP Server**. +Use the built-in `POST /api/v1/mcp` route, or enable the optional listener when you need a separate `/mcp` endpoint or legacy SSE. Both are owned by the Go API process and call RAGFlow services directly. -For details about the MCP tools exposed by RAGFlow and their parameters, see **RAGFlow MCP Tools**. +See [Use RAGFlow as an MCP Server](./use_ragflow_as_mcp_server.md) for endpoints and authentication, [RAGFlow MCP Tools](./mcp_tools.md) for the registered tools, and [RAGFlow MCP Client Examples](./mcp_client_example.md) for requests. -For examples of calling the RAGFlow MCP server with Python or curl, see **RAGFlow MCP Client Examples**. +## Connect an external MCP server to RAGFlow -### Connect an external MCP server to RAGFlow - -RAGFlow can also connect to third-party or self-hosted MCP servers and discover the MCP tools they provide. - -Once configured, these tools can be used by RAGFlow Agents, allowing agents to interact with external systems and services. - -A typical request flow is: +RAGFlow can also connect to third-party or self-hosted MCP servers. Their tools become available to RAGFlow Agents. ```text -External MCP Server - ↓ - RAGFlow - ↓ - Agent +External MCP server → RAGFlow Agent → tool invocation ``` -For information about configuring, testing, and using external MCP servers, see **Connect an External MCP Server to RAGFlow**. - -## Choose the right MCP scenario - -Choose an MCP usage scenario based on what y +See [Connect an External MCP Server to RAGFlow](./connect_an_external_mcp_to_ragflow.md) for supported transports, connection requirements, and an example. diff --git a/docs/develop/mcp/use_ragflow_as_mcp_server.md b/docs/develop/mcp/use_ragflow_as_mcp_server.md index f707c0eca5..0a9744152f 100644 --- a/docs/develop/mcp/use_ragflow_as_mcp_server.md +++ b/docs/develop/mcp/use_ragflow_as_mcp_server.md @@ -9,141 +9,77 @@ sidebar_custom_props: # Use RAGFlow as an MCP Server -RAGFlow can act as an MCP server and expose its capabilities to external MCP clients. - -The Python-based RAGFlow MCP server runs as a standalone component alongside RAGFlow. It communicates with the RAGFlow server through the RAGFlow API and exposes RAGFlow capabilities through the Model Context Protocol (MCP). - -To start and configure the server, see [Launch RAGFlow MCP Server](./launch_mcp_server.md). - -For details about the MCP tools exposed by RAGFlow, see [RAGFlow MCP Tools](./mcp_tools.md). - -For examples of calling the RAGFlow MCP server from an MCP client, see [RAGFlow MCP Client Examples](./mcp_client_example.md). - -## How it works - -The Python MCP server runs independently from the RAGFlow server. - -A typical request flow is: +RAGFlow's Go API server exposes MCP tools through its built-in MCP endpoint. ```text -External MCP Client - ↓ -RAGFlow MCP Server - ↓ -RAGFlow API - ↓ -RAGFlow capabilities +External MCP client → Go MCP endpoint → RAGFlow services ``` -The MCP server receives requests from external MCP clients and forwards the corresponding operations to RAGFlow through its API. +## Choose an endpoint -By default, the MCP server listens on port `9382`. +| Endpoint | Availability | Transport | Authentication | +| --- | --- | --- | --- | +| `POST /api/v1/mcp` on the Go API port | Available while the Go API runs | Streamable HTTP with JSON responses | Each client sends its RAGFlow credential in `Authorization`. | +| `/mcp` on the optional MCP listener | Enable `mcp.enabled` or `RAGFLOW_MCP_ENABLED` | Streamable HTTP; legacy SSE at `/sse` and `/messages/` when enabled | `host` mode authenticates each request; `self-host` mode uses one configured key for all clients. | -## Prerequisites +For a local binary, start the API with `bin/ragflow_server --api --config conf/service_conf.yaml`. The target Go API port is `9380`, so its direct endpoint is `http://127.0.0.1:9380/api/v1/mcp`. Use the configured address if your port or reverse proxy differs. This API route accepts POST requests; it does not provide the legacy SSE paths. -Before starting the RAGFlow MCP server, ensure that: +## Enable the optional MCP listener -* RAGFlow is deployed and running normally. -* The RAGFlow API is accessible from the MCP server. -* A valid RAGFlow user has been created. -* A RAGFlow API key is available if you use Self-host mode. -* The MCP client can access the MCP server. -* The required Python dependencies are installed if you start the MCP server from source. +The Go API process also owns an optional listener. It is disabled by default and binds to `127.0.0.1:9382` unless configured otherwise. Uncomment or add this example in `conf/service_conf.yaml` for local use: -## Launch modes - -The RAGFlow MCP server supports two launch modes: - -* **Self-host mode** -* **Host mode** - -The main difference is how RAGFlow user authentication is handled. - -### Self-host mode - -In Self-host mode, the RAGFlow API key is specified when the MCP server starts. - -The MCP server uses this API key for requests sent to RAGFlow. All MCP clients connected to this server therefore access RAGFlow using the same RAGFlow user identity. - -The request flow is: - -```text -External MCP Client - ↓ -RAGFlow MCP Server - ↓ -Configured RAGFlow API Key - ↓ -RAGFlow Server +```yaml +mcp: + enabled: true + host: 127.0.0.1 + port: 9382 + launch_mode: host + transport_sse_enabled: true + transport_streamable_enabled: true + json_response: true ``` -Self-host mode is suitable when the MCP server is dedicated to a specific RAGFlow user or trusted environment. +Start the Go API with `bin/ragflow_server --api --config conf/service_conf.yaml`. The listener's Streamable HTTP URL is `http://127.0.0.1:9382/mcp`. If SSE is enabled, legacy clients use `http://127.0.0.1:9382/sse` and send messages to `/messages/`. -### Host mode +Environment variables override YAML settings: -In Host mode, the MCP server is not bound to a fixed RAGFlow user when it starts. +| Environment variable | YAML field under `mcp` | Default | +| --- | --- | --- | +| `RAGFLOW_MCP_ENABLED` | `enabled` | `false` | +| `RAGFLOW_MCP_HOST` | `host` | `127.0.0.1` | +| `RAGFLOW_MCP_PORT` | `port` | `9382` | +| `RAGFLOW_MCP_LAUNCH_MODE` | `launch_mode` | `self-host` | +| `RAGFLOW_MCP_HOST_API_KEY` | `host_api_key` | empty | +| `RAGFLOW_MCP_TRANSPORT_SSE_ENABLED` | `transport_sse_enabled` | `true` | +| `RAGFLOW_MCP_TRANSPORT_STREAMABLE_ENABLED` | `transport_streamable_enabled` | `true` | +| `RAGFLOW_MCP_JSON_RESPONSE` | `json_response` | `true` | -Instead, each MCP client provides its own authentication information. RAGFlow determines the user and resource permissions based on the credentials provided by that client. +Boolean values `1`, `true`, `yes`, and `on` are true, regardless of case. An explicitly empty environment value also overrides YAML. An empty host binds all interfaces. If both transports are disabled, Streamable HTTP is re-enabled with streamed responses. Invalid ports or launch modes prevent startup. -The request flow is: +## Authentication -```text -External MCP Client - ↓ -Client authentication - ↓ -RAGFlow MCP Server - ↓ -RAGFlow Server +The optional listener supports two modes: + +| Mode | Credential handling | +| --- | --- | +| `host` | Every request is authenticated as its client. Prefer `Authorization: Bearer `; `api_key`, `X-API-Key`, and `Api-Key` headers are also accepted. Both Streamable HTTP and SSE work in this mode. | +| `self-host` (default) | Set `mcp.host_api_key` or `RAGFLOW_MCP_HOST_API_KEY` before startup. Every connected client uses the configured user's identity, regardless of its own headers. Restrict access to trusted clients. | + +Enabling the listener with its default `self-host` mode requires `mcp.host_api_key` or `RAGFLOW_MCP_HOST_API_KEY`; startup fails when that key is empty. The configured key is checked at startup and for each request, so revoking it takes effect. Keep keys out of command arguments and committed files. The `/api/v1/mcp` API route always authenticates each client through its own `Authorization` header; listener launch modes do not change that route. + +## Docker + +For the Go deployment, use `docker/docker-compose.yml` with `docker/.env`. Uncomment the `mcp` example in `docker/service_conf.yaml.template` or set the equivalent `RAGFLOW_MCP_*` values in `docker/.env`. The Go entrypoint generates the runtime configuration from that template. + +To connect to the optional listener from outside the container, set its host to `0.0.0.0` and add this mapping under the `ragflow-cpu` service's `ports` in `docker/docker-compose.yml`: + +```yaml +ports: + - ${SVR_MCP_PORT}:9382 ``` -Host mode is more suitable when a shared MCP server needs to serve multiple RAGFlow users. +The checked-in Go Compose file does not publish port `9382` by default. `SVR_MCP_PORT` is defined in `docker/.env`. Adjust the container-side port if you change `mcp.port`. Use `host` mode when external clients must authenticate individually. -## Transport protocols +## Verify the endpoint -The Python MCP server supports the following transports: - -* **Streamable HTTP** -* **SSE** - -### Streamable HTTP - -Streamable HTTP uses the following endpoint: - -```text -/mcp -``` - -For example: - -```text -http://127.0.0.1:9382/mcp -``` - -Streamable HTTP should be preferred for MCP clients that support it. - -### SSE - -The MCP server also supports the legacy SSE transport. - -The SSE endpoint is: - -```text -/sse -``` - -Messages are sent through: - -```text -/messages/ -``` - -For example: - -```text -http://127.0.0.1:9382/sse -``` - -SSE is retained for compatibility with MCP clients that still use the legacy MCP transport. - -> When using Host mode, check the transport requirements of +Use [RAGFlow MCP Client Examples](./mcp_client_example.md) to initialize the endpoint, list its tools, and call a tool. A successful initialization response contains an MCP `result` with `serverInfo`. For the API route, use your Go API address ending in `/api/v1/mcp`; for the optional listener, use its `/mcp` URL. See [RAGFlow MCP Tools](./mcp_tools.md) for the available tools. diff --git a/docs/develop/switch_doc_engine.md b/docs/develop/switch_doc_engine.md index 1c24cd3065..c2bdea4a5e 100644 --- a/docs/develop/switch_doc_engine.md +++ b/docs/develop/switch_doc_engine.md @@ -15,24 +15,24 @@ Switch your doc engine from Elasticsearch to Infinity. RAGFlow uses Elasticsearch by default for storing full text and vectors. To switch to [Infinity](https://github.com/infiniflow/infinity/), follow these steps: -:::caution WARNING -Switching to Infinity on a Linux/arm64 machine is not yet officially supported. -::: +1. Back up the existing deployment before switching engines. Switching engines creates a new document-index store; reindex the documents after startup. -1. Stop all running containers: +2. Stop the Go deployment: ```bash - $ docker compose -f docker/docker-compose.yml down -v + docker compose --env-file docker/.env -f docker/docker-compose.yml down ``` :::caution WARNING -`-v` will delete the docker container volumes, and the existing data will be cleared. +Do not add `-v` unless you intentionally want to delete the deployment's data volumes. ::: -2. Set `DOC_ENGINE` in **docker/.env** to `infinity`. +3. Set `DOC_ENGINE=infinity` in **docker/.env**. -3. Start the containers: +4. Start the Go deployment: ```bash - $ docker compose -f docker-compose.yml up -d + docker compose --env-file docker/.env -f docker/docker-compose.yml up -d ``` + +5. Reindex the documents and verify retrieval before retiring the previous document-engine data. diff --git a/docs/faq.mdx b/docs/faq.mdx index 2c4c02a6d2..757acb5e7b 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -31,81 +31,59 @@ RAGFlow provides an end-to-end RAG platform that goes beyond basic document chun --- ---- - -### Where to find the version of RAGFlow? How to interpret it? +### Where can I find the RAGFlow version, and how do I interpret it? You can find the RAGFlow version number on the **System** page of the UI: ![Image](https://github.com/user-attachments/assets/20cf7213-2537-4e18-a88c-4dadf6228c6b) -If you build RAGFlow from source, the version number is also in the system log: +If you build RAGFlow from source, the Go admin and ingestor log their versions at startup. The server also prints its version with `bin/ragflow_server --api --version`. -``` - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - -2025-02-18 10:10:43,835 INFO 1445658 RAGFlow version: v0.15.0-50-g6daae7f2 -``` - -Where: - -- `v0.15.0`: The officially published release. -- `50`: The number of git commits since the official release. -- `g6daae7f2`: `g` is the prefix, and `6daae7f2` is the first seven characters of the current commit ID. +For example, `v0.27.1-14-g6daae7f2` means 14 commits after the `v0.27.1` tag, at a commit whose abbreviated ID is `6daae7f2`. The actual value comes from the packaged `VERSION` file or, when that file is absent, from `git describe`; it may be a tag alone or `unknown` if neither source supplies a version. --- -### Why does RAGFlow use Elasticsearch or Infinity as its default document engine? +### Why does RAGFlow use Elasticsearch as its default document engine? -Elasticsearch and [Infinity](https://github.com/infiniflow/infinity) meet RAGFlow's core hybrid search requirements, including full-text search, vector search, phrase search, and advanced ranking capabilities. -RAGFlow also supports other document engines, including OpenSearch, OceanBase, SeekDB, and GaussDB. Support levels and available features may vary between document engines. -[Infinity](https://github.com/infiniflow/infinity) is an AI-native database developed by InfiniFlow and optimized for RAG workloads. +Elasticsearch meets RAGFlow's core hybrid search requirements, including full-text search, vector search, phrase search, and advanced ranking capabilities. + +The Go backend also supports [Infinity](https://github.com/infiniflow/infinity) as a document engine. Infinity is an AI-native database developed by InfiniFlow and optimized for RAG workloads. Support levels and available features may vary between document engines. --- -### Differences between cloud.ragflow.io and a locally deployed open-source RAGFlow service? +### What are the differences between cloud.ragflow.io and a locally deployed open-source RAGFlow service? -cloud.ragflow.io demonstrates the capabilities of RAGFlow Enterprise. Its DeepDoc models are pre-trained using proprietary data and it offers much more sophisticated team permission controls. Essentially, cloud.ragflow.io serves as a preview of RAGFlow's forthcoming SaaS (Software as a Service) offering. +cloud.ragflow.io is the hosted RAGFlow service. It provides managed infrastructure and subscription-based limits and features, while a locally deployed open-source service gives you control over deployment, data, models, storage, and system resources. -You can deploy an open-source RAGFlow service and call it from a Python client or through RESTful APIs. However, this is not supported on cloud.ragflow.io. +REST API access on cloud.ragflow.io depends on the subscription plan. Check the current plan details on the [RAGFlow website](https://ragflow.io/) before relying on API access. A locally deployed service exposes the RAGFlow HTTP APIs directly and uses API keys created in its UI. --- ### Why does RAGFlow require substantial system resources? -RAGFlow runs multiple components for document parsing, embedding, full-text and vector indexing, retrieval, task processing, metadata storage, caching, and object storage. Some document parsers also load or download machine-learning models and may require significant memory or GPU resources. +RAGFlow runs multiple components for document parsing, embedding, full-text and vector indexing, retrieval, task processing, metadata storage, caching, and object storage. Some document parsers also load or download machine-learning models and may require significant CPU and memory resources. -Actual resource usage depends on the selected document engine, parser, model provider, document volume, and workload. See the deployment prerequisites and configuration documentation for the current minimum requirements. +Actual resource usage depends on the selected document engine, parser, model provider, document volume, and workload. See the [quickstart prerequisites](./quickstart.mdx#prerequisites) for the recommended starting configuration. --- ### Which architectures or devices does RAGFlow support? -We officially support x86 CPUs and NVIDIA GPUs. While we also test RAGFlow on ARM64 platforms, we do not maintain RAGFlow Docker images for ARM. If you are on an ARM platform, follow [this guide](./develop/build_docker_image.mdx) to build a RAGFlow Docker image. +The documented Go image build targets Linux AMD64. Building on another architecture requires a matching dependency image and native libraries, and the selected document engine must support that architecture. The commands in the [quickstart guide](./quickstart.mdx#start-up-the-server) target AMD64. --- ### Do you offer an API for integration with third-party applications? -The corresponding APIs are now available. See the [RAGFlow HTTP API Reference](./references/http_api_reference.md) or the [RAGFlow Python API Reference](./references/python_api_reference.md) for more information. +See the [RAGFlow HTTP API Reference](./references/http_api_reference.md) for integration endpoints. --- ### Do you support stream output? -Yes, we do. Stream output is enabled by default in the chat assistant and agent. Note that you cannot disable stream output via RAGFlow's UI. To disable stream output in responses, use RAGFlow's Python or RESTful APIs: +Yes. RAGFlow supports both streaming and non-streaming responses. The interactive Chat and Agent pages display responses as they are generated, while the embedded chat configuration provides an **Enable streaming responses** option. -Python: - -- [Create chat completion](./references/python_api_reference.md#create-chat-completion) -- [Converse with chat assistant](./references/python_api_reference.md#converse-with-chat-assistant) -- [Converse with agent](./references/python_api_reference.md#converse-with-agent) - -RESTful: +For HTTP API calls, use the endpoint's `stream` parameter to select the response mode. Defaults can differ between endpoints, so check the corresponding API reference: - [Create chat completion](./references/http_api_reference.md#create-chat-completion) - [Converse with chat assistant](./references/http_api_reference.md#converse-with-chat-assistant) @@ -113,7 +91,7 @@ RESTful: --- -### Key differences between search and chat? +### What are the key differences between Search and Chat? - **Search** is designed for direct knowledge retrieval. It retrieves and ranks relevant content from one or more datasets and presents the results for users to review. - **Chat** is designed for conversational question answering. It retrieves relevant knowledge and uses an LLM to generate answers, supporting multi-turn conversations and more advanced retrieval capabilities such as Agentic Retrieval. @@ -126,289 +104,171 @@ Use **Search** when you want to find and inspect relevant knowledge directly, an --- -### Get a `Request error 404: undefined` when upgrading to v0.27.2 +### How do I build a RAGFlow image from scratch? -To resolve this issue, do either of the following: - -- Pull the latest source code from the [main branch](https://github.com/infiniflow/ragflow), then pull and start the v0.27.2 image. -- Update `RAGFLOW_IMAGE` from `infiniflow/ragflow:latest` to `infiniflow/ragflow:v0.27.2` in the [.env file](https://github.com/infiniflow/ragflow/blob/main/docker/.env), then restart the service. - -### How to build the RAGFlow image from scratch? - -See [Build a RAGFlow Docker image](./develop/build_docker_image.mdx). +Build the Go image from the repository root with `Dockerfile`, then set `RAGFLOW_IMAGE` in **docker/.env**. See the [quickstart guide](./quickstart.mdx#start-up-the-server) for the current commands and prerequisites. --- -### PDF parsing fails because required Hugging Face models cannot be downloaded +### Why does PDF parsing fail when DeepDoc model files are missing? -Some RAGFlow document parsers download required model files from [Hugging Face](https://huggingface.co). If the RAGFlow container cannot access Hugging Face and the files are not already cached, model initialization or document parsing may fail. - -For example: - -``` -FileNotFoundError: [Errno 2] No such file or directory: '/root/.cache/huggingface/hub/models--InfiniFlow--deepdoc/snapshots/be0c1e50eef6047b412d1800aa89aba4d275f997/ocr.res' -``` - -To fix this issue, use https://hf-mirror.com instead: - -1. Stop all containers and remove all related resources: - - ```bash - cd ragflow/docker/ - docker compose down - ``` - -2. Uncomment the following line in **ragflow/docker/.env**: - - ``` - # HF_ENDPOINT=https://hf-mirror.com - ``` - -3. Start up the server: - - ```bash - docker compose up -d - ``` +The Go API and ingestor initialize the in-process DeepDoc backend. Check their logs for model initialization errors and verify that the configured `DEEPDOC_MODEL_DIR` contains the required model files, including `det.ort`, `layout.ort`, `tsr.ort`, `rec.ort`, and `ocr.res`. If you use the shared model asset directory, check `MODEL_ASSETS_DIR` instead. Restore the missing files from the deployment's model assets, then restart the affected service. --- -### `Fail to access model(Ollama/xxxxx)` +### Does the open-source 1.0 Go DeepDoc backend support GPU inference? -This error means that RAGFlow cannot access the configured Ollama model. Check that Ollama is running, the model has been downloaded, the model name is correct, and the Ollama Base URL is reachable from the RAGFlow container. +No. The RAGFlow open-source 1.0 Go DeepDoc backend runs layout analysis, OCR, and table recognition on CPU. + +--- + +### Why can't RAGFlow access my Ollama model? + +Check that Ollama is running, the model has been downloaded, the model name is correct, and the Ollama Base URL is reachable from the RAGFlow container. If the request times out while loading the model, check the Ollama logs and available memory. Try a smaller model or allocate more memory if necessary. See [Deploy a local LLM](./guides/models/deploy_local_llm.mdx) for more information. ---- - -### `MaxRetryError: HTTPSConnectionPool(host='hf-mirror.com', port=443)` - -This error suggests that you do not have Internet access or are unable to connect to hf-mirror.com. Try the following: - -1. Manually download the resource files from [huggingface.co/InfiniFlow/deepdoc](https://huggingface.co/InfiniFlow/deepdoc) to your local folder **~/deepdoc**. -2. Add a volume mapping to **docker/docker-compose.yml**, for example: - - ``` - - ~/deepdoc:/ragflow/rag/res/deepdoc - ``` +For setup instructions, see [How do I use Ollama with RAGFlow for local LLM inference?](#how-do-i-use-ollama-with-ragflow-for-local-llm-inference) --- -### `RuntimeError: Unable to start Tika server.` +### Why can't Nginx reach the Go API? -This error is almost always caused by Java not being installed or not accessible in the environment. See [here](https://github.com/infiniflow/ragflow/issues/13194) for detailed instructions. +Check that the Go API and Admin services started, then review the RAGFlow container and Nginx logs. In the target Go configuration, Nginx forwards API requests to port `9380` and Admin requests to port `9381`. Check the active `ragflow.conf` against `docker/nginx/ragflow.conf.golang` and verify that those services are listening before changing the proxy configuration. --- -### `Cannot stat '/etc/nginx/conf.d/ragflow.conf.python': No such file or directory` - -To resolve this, either download the missing file from the corresponding tag on [GitHub](https://github.com/infiniflow/ragflow) or update `~/ragflow/docker/docker-compose.yml` as follows: - -![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/docker-compose_missing.jpg) - ---- - -### `network anomaly There is an abnormality in your network and you cannot connect to the server.` +### What does `network anomaly: There is an abnormality in your network and you cannot connect to the server` mean? ![anomaly](https://github.com/infiniflow/ragflow/assets/93570324/beb7ad10-92e4-4a58-8886-bfb7cbd09e5d) -You will not log in to RAGFlow unless the server is fully initialized. Run `docker logs -f docker-ragflow-cpu-1`. - -*The server is successfully initialized, if your system displays the following:* +You cannot log in until the services are initialized. Review the RAGFlow container logs (`docker compose --env-file docker/.env -f docker/docker-compose.yml logs -f ragflow-cpu` from the repository root). The Go services log these startup messages: +```text +Starting api server: ... +Server starting on port: 9380 +Starting admin server: ... +Starting RAGFlow admin HTTP server on port: 9381 +Starting ingestor server: ... +Ingestor ... initialized +RAGFlow ingestion service version: ... ``` - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - * Running on all addresses (0.0.0.0) - * Running on http://127.0.0.1:9380 - * Running on http://x.x.x.x:9380 -``` -Then use the [system health API](./references/http_api_reference.md#check-system-health) to check the database, Redis, document engine, and object storage. +These messages come from separate processes and may appear in a different order. Check the logs for startup errors, use the [system health API](./references/http_api_reference.md#check-system-health) to inspect dependencies, and verify that the ingestor has registered with admin before treating document parsing as ready. --- -### `Realtime synonym is disabled, since no redis connection` +### Why are document tasks waiting in the queue? -Ignore this warning and continue. All system warnings can be ignored. +The Go ingestor consumes document tasks from NATS JetStream. A growing queue can mean that no ingestor is consuming, workers are busy, or tasks are repeatedly failing. -![](https://github.com/infiniflow/ragflow/assets/93570324/ef5a6194-084a-4fe3-bdd5-1c025b40865c) +1. Check that the NATS and RAGFlow containers are running, and inspect their logs for connection or consumer errors. +2. Check the ingestor logs for `Ingestor ... initialized`, `NATS stream RAGFLOW_TASKS ready`, pull errors, and task failures. Confirm that the ingestor is registered with admin. +3. Check whether workers are processing tasks and whether the task status or document progress changes. Investigate the first task error before retrying it. + +Do not clear the queue as a first troubleshooting step: doing so can discard pending work. --- -### `xxx tasks are ahead in the queue` - -#### For RAGFlow versions earlier than v0.26.0 - -1. Clear the Redis task queue: - -```bash -$ docker exec -it ragflow-redis /bin/bash -# In container -$ redis-cli -a infini_rag_flow -# In redis-cli -select 1 -XGROUP DESTROY rag_flow_svr_queue rag_flow_svr_task_broker -XGROUP CREATE rag_flow_svr_queue rag_flow_svr_task_broker $ MKSTREAM -# When CREATE raises and error: -FLUSHDB -``` - -2. If the parser remains stuck at 0%, restart the RAGFlow containers using one of the following methods: - -```bash -# Option 1: Restart specific container -docker restart docker-redis-1 docker-ragflow-cpu-1 - -# Option 2: Recreate containers via Docker Compose -docker compose -f docker/docker-compose.yml down -docker compose -f docker/docker-compose.yml up -d - -# Option 3: Reset all Docker containers -# WARNING: Run this ONLY if your environment contains no other non-RAGFlow containers. -docker stop $(docker ps -aq) -docker rm $(docker ps -aq) -``` - -#### For RAGFlow v0.26.0 and later - -1. Clear the Redis task queue: - -```bash -$ docker exec -it ragflow-redis /bin/bash -# In container -$ redis-cli -a infini_rag_flow -# In redis-cli -select 1 -XGROUP DESTROY te.0.common rag_flow_svr_task_broker -XGROUP CREATE te.0.common rag_flow_svr_task_broker $ MKSTREAM - -XGROUP DESTROY te.1.common rag_flow_svr_task_broker -XGROUP CREATE te.1.common rag_flow_svr_task_broker $ MKSTREAM -``` - -2. If the parser remains stuck at 0%, restart the RAGFlow containers using one of the following methods: - -```bash -# Option 1: Restart specific container -docker restart docker-redis-1 docker-ragflow-cpu-1 - -# Option 2: Recreate containers via Docker Compose -docker compose -f docker/docker-compose.yml down -docker compose -f docker/docker-compose.yml up -d - -# Option 3: Reset all Docker containers -# WARNING: Run this ONLY if your environment contains no other non-RAGFlow containers. -docker stop $(docker ps -aq) -docker rm $(docker ps -aq) -``` - ---- - -### Why does my document parsing stall at under one percent? +### Why does document parsing stall below 1%? ![stall](https://github.com/infiniflow/ragflow/assets/93570324/3589cc25-c733-47d5-bbfc-fedb74a3da50) Click the red cross beside the 'parsing status' bar, then restart the parsing process to see if the issue remains. If the issue persists and your RAGFlow is deployed locally, try the following: -1. Check the log of your RAGFlow server to see if it is running properly: +1. Check the RAGFlow container logs for API, admin, and ingestor startup errors: ```bash - docker logs -f docker-ragflow-cpu-1 + docker compose --env-file docker/.env -f docker/docker-compose.yml logs -f ragflow-cpu ``` -2. Check if the **task_executor.py** process exists. -3. Check if your RAGFlow server can access hf-mirror.com or huggingface.com. + +2. Confirm that the Go ingestor is running and sending heartbeats to admin. Check admin's service status for the ingestor; an API health response alone does not confirm that workers are consuming tasks. +3. Check the NATS connection and JetStream consumer in the logs. Look for pull errors, consumer initialization failures, and repeated task failures. +4. Check the parser and tokenizer assets separately. Missing DeepDoc model files prevent the API or ingestor from starting because the in-process DeepDoc backend is required. A missing `cl100k_base.tiktoken` table does not normally prevent startup, but ingestion fails for models that declare that tokenizer until the table is restored. +5. Check whether ingestor workers are processing tasks and whether task progress changes. If a worker stops making progress, inspect its task error and available memory before retrying. --- -### Why does my pdf parsing stall near completion, while the log does not show any error? +### Why does PDF parsing stall near completion without any errors in the logs? -Click the red cross beside the 'parsing status' bar, then restart the parsing process to see if the issue remains. If the issue persists and your RAGFlow is deployed locally, the parsing process is likely killed due to insufficient RAM. Try increasing your memory allocation by increasing the `MEM_LIMIT` value in **docker/.env**. +Click the red cross beside the 'parsing status' bar, then restart the parsing process to see if the issue remains. If the issue persists, check the ingestor and container logs for an out-of-memory error. Make sure the Docker runtime or host has enough memory available for the RAGFlow service, and reduce concurrent parsing work if necessary. :::note -Ensure that you restart up your RAGFlow server for your changes to take effect! - -```bash -docker compose stop -``` - -```bash -docker compose up -d -``` - +The standard Go Compose file does not apply `MEM_LIMIT` to `ragflow-cpu`; that variable limits selected dependency services. Changing it does not increase the memory available to the Go ingestor. Adjust the Docker runtime or host allocation, or add an explicit service-level memory limit in a Compose override if your environment requires one. ::: ![nearcompletion](https://github.com/infiniflow/ragflow/assets/93570324/563974c3-f8bb-4ec8-b241-adcda8929cbb) --- -### `Index failure` +### What does `Index failure` mean? An index failure means that RAGFlow could not write the processed document chunks to the configured document engine. -Check the task logs, embedding model, document engine connection, and system health. If you use Elasticsearch, OpenSearch, Infinity, or another supported document engine, verify that the corresponding service is running and accessible. +Check the task logs, embedding model, document engine connection, and system health. If you use Elasticsearch, Infinity, or another document engine supported by the current Go backend, verify that the corresponding service is running and accessible. --- -### How to check the log of RAGFlow? +### How do I check RAGFlow logs? + +From the repository root, follow the Go service logs written to the mounted log directory: ```bash -tail -f ragflow/docker/ragflow-logs/*.log +tail -f docker/ragflow-logs/*.log ``` +To view the container's combined output, use `docker compose --env-file docker/.env -f docker/docker-compose.yml logs -f ragflow-cpu`. + --- -### How to check the status of each component in RAGFlow? +### How do I check the status of each RAGFlow component? -1. Check the status of the RAGFlow Docker container: +1. From the repository root, check the Go deployment's containers: ```bash - $ docker compose ps + docker compose --env-file docker/.env -f docker/docker-compose.yml ps ``` - Review the service logs: + + Review the RAGFlow service logs: + ```bash - docker compose logs -f ragflow - + docker compose --env-file docker/.env -f docker/docker-compose.yml logs -f ragflow-cpu ``` -2. Use the [system health API](./references/http_api_reference.md#check-system-health) to check the database, Redis, document engine, and object storage. + Check the `nats` and selected document engine services in the same Compose project when diagnosing ingestion or indexing. + +2. Use the [system health API](./references/http_api_reference.md#check-system-health) to check the database, Kvrocks cache, document engine, object storage, and NATS message queue. A running container does not necessarily mean that the service inside it is healthy. Check the health API and logs for connection, port, DNS, and configuration errors. --- -### `Exception: Can't connect to ES cluster` +### Why can't RAGFlow connect to Elasticsearch? 1. Check the status of the Elasticsearch Docker container: ```bash - $ docker ps + docker compose --env-file docker/.env -f docker/docker-compose.yml ps es01 ``` - *The status of a healthy Elasticsearch component should look as follows:* - - ``` - 91220e3285dd docker.elastic.co/elasticsearch/elasticsearch:8.11.3 "/bin/tini -- /usr/l…" 11 hours ago Up 11 hours (healthy) 9300/tcp, 0.0.0.0:9200->9200/tcp, :::9200->9200/tcp ragflow-es-01 - ``` + A healthy Elasticsearch container should report `healthy`. The default Go Compose deployment exposes Elasticsearch on host port `1200`, while the container listens on port `9200`. 2. Follow [the system health API](./references/http_api_reference.md#check-system-health) to check the health status of the Elasticsearch service. :::danger IMPORTANT - The status of a Docker container status does not necessarily reflect the status of the service. You may find that your services are unhealthy even when the corresponding Docker containers are up running. Possible reasons for this include network failures, incorrect port numbers, or DNS issues. + The status of a Docker container does not necessarily reflect the status of the service inside it. A service can be unhealthy even when its container is up and running. Possible causes include network failures, incorrect ports, and DNS or configuration errors. ::: 3. If your container keeps restarting, ensure `vm.max_map_count` >= 262144. On Linux, update **/etc/sysctl.conf** to keep the change permanent. For macOS, see the following FAQ. --- -### Can't start ES container and get `Elasticsearch did not exit normally` +### Why does the Elasticsearch container fail to start with `Elasticsearch did not exit normally`? -On Linux, this is because you forgot to update the `vm.max_map_count` value in **/etc/sysctl.conf** and your change to this value was reset after a system reboot. +On Linux, an insufficient `vm.max_map_count` value is a common cause. Check the Elasticsearch logs first. If they report that `vm.max_map_count` is too low, set it to at least 262144 and add the setting to **/etc/sysctl.conf** so it persists after a reboot. If the logs report a different error, check memory, disk space, permissions, and the Elasticsearch data directory instead. --- @@ -457,53 +317,51 @@ colima start --- -### `{"data":null,"code":100,"message":""}` +### Why does the Go API return a 404 response? -Your IP address or port number may be incorrect. If you are using the default configurations, enter `http://` (**NOT 9380, AND NO PORT NUMBER REQUIRED!**) in your browser. This should work. +The Go API returns HTTP 404 with `Not Found: ` when a request does not match a route. Your URL may point to the wrong service. + +For normal UI and API access, use `http://` when `SVR_WEB_HTTP_PORT` is 80, or include the configured web port. Nginx forwards API traffic to the Go API on internal port `9380` and Admin traffic to internal port `9381`. + +The Go Compose deployment uses `SVR_HTTP_PORT` and `ADMIN_SVR_HTTP_PORT` for the directly published API and Admin host ports. For normal browser and API access, prefer the Nginx web port. --- -### `Ollama - Mistral instance running at 127.0.0.1:11434 but cannot add Ollama as model in RagFlow` +### Do you provide examples of using DeepDoc to parse PDFs or other files? -A correct Ollama IP address and port is crucial to adding models to Ollama: +Yes. The Go parser implementations are in `internal/parser/parser`, and the Go DeepDoc integration is in `internal/deepdoc`. The following tests provide concrete usage examples: -- If you are on cloud.ragflow.io, ensure that the server hosting Ollama has a publicly accessible IP address. Note that 127.0.0.1 is not a publicly accessible IP address. -- If you deploy RAGFlow locally, ensure that Ollama and RAGFlow are in the same LAN and can communicate with each other. +- [`internal/deepdoc/parser/pdf/parser_pipeline_integration_test.go`](https://github.com/infiniflow/ragflow/blob/main/internal/deepdoc/parser/pdf/parser_pipeline_integration_test.go) demonstrates the PDF parsing and post-processing pipeline. +- [`internal/deepdoc/parser/docx/parser_integration_test.go`](https://github.com/infiniflow/ragflow/blob/main/internal/deepdoc/parser/docx/parser_integration_test.go) demonstrates DOCX parsing. +- [`internal/parser/parser/pdf_parser_pages_e2e_test.go`](https://github.com/infiniflow/ragflow/blob/main/internal/parser/parser/pdf_parser_pages_e2e_test.go) demonstrates configuring and calling the higher-level PDF parser adapter. -See [Deploy a local LLM](./guides/models/deploy_local_llm.mdx) for more information. +RAGFlow's ingestor uses these components when it processes documents. These files are integration or end-to-end tests, so review their prerequisites and build constraints before running them directly. --- -### Do you offer examples of using DeepDoc to parse PDF or other files? +### Why can't RAGFlow find a required file? -Yes. See the parser entry points and examples in the [`rag/app`](https://github.com/infiniflow/ragflow/tree/main/rag/app) directory. - -For example, `rag/app/naive.py` shows how RAGFlow selects and invokes document parsers for different file types. - ---- - -### `FileNotFoundError: [Errno 2] No such file or directory` - -This error means that RAGFlow cannot find a required file. Check the complete error message and stack trace to identify the missing path. +Check the complete Go error message and surrounding logs to identify the missing path. - If a model file is missing, check whether the required model was downloaded successfully. - If an uploaded document is missing, check the configured object storage service. - If a temporary or local file is missing, check the container volume mappings and file permissions. Use the [system health API](./references/http_api_reference.md#check-system-health) to verify the configured object storage and other dependencies. + --- ## Usage --- -### How to run RAGFlow with a locally deployed LLM? +### How do I run RAGFlow with a locally deployed LLM? -You can use Ollama or Xinference to deploy local LLM. See [here](./guides/models/deploy_local_llm.mdx) for more information. +You can use Ollama or Xinference to deploy a local LLM. See [Deploy a local LLM](./guides/models/deploy_local_llm.mdx) for configuration details. --- -### How to add an LLM that is not supported? +### How do I add an LLM that is not directly supported? If your model is not currently supported but has APIs compatible with those of OpenAI, click **OpenAI-API-Compatible** on the **Model providers** page to configure your model: @@ -511,82 +369,88 @@ If your model is not currently supported but has APIs compatible with those of O --- -### How to integrate RAGFlow with Ollama? +### How do I change the file size limit? -- If RAGFlow is locally deployed, ensure that your RAGFlow and Ollama are in the same LAN. -- If you are using our online demo, ensure that the IP address of your Ollama server is public and accessible. +The Go file-manager upload endpoint allows up to 1 GiB per file by default. The dataset document upload path has a separate 128 MiB per-file limit. Check which upload endpoint rejected the file before changing deployment settings. -See [here](./guides/models/deploy_local_llm.mdx) for more information. +To change the file-manager upload limit in a Go Compose deployment, set `MAX_CONTENT_LENGTH` in **docker/.env** to the desired number of bytes. The default 1 GiB value is `1073741824`. + +If you raise the limit above 1 GiB, also increase `client_max_body_size` in **docker/nginx/nginx.conf**. The Go image contains its own copy of this file, so make the change effective by either rebuilding `RAGFLOW_IMAGE` or enabling the `./nginx/nginx.conf:/etc/nginx/nginx.conf` bind mount for the deployed service in **docker/docker-compose.yml**, then recreate that service. Lowering `MAX_CONTENT_LENGTH` below 1 GiB does not require changing the default Nginx limit. + +These settings do not raise the dataset document upload path's fixed 128 MiB limit. --- -### How to change the file size limit? +### How do I get an API key for integration with third-party applications? -For a locally deployed RAGFlow: the total file size limit per upload is 1GB, with a batch upload limit of 32 files. There is no cap on the total number of files per account. To update this 1GB file size limit: - -- In **docker/.env**, uncomment `# MAX_CONTENT_LENGTH=1073741824`, adjust the value as needed, and note that `1073741824` represents 1GB in bytes. -- If you update the value of `MAX_CONTENT_LENGTH` in **docker/.env**, ensure that you update `client_max_body_size` in **nginx/nginx.conf** accordingly. - -:::tip NOTE -It is not recommended to manually change the 32-file batch upload limit. However, if you use RAGFlow's HTTP API or Python SDK to upload files, the 32-file batch upload limit is automatically removed. -::: +In the RAGFlow UI, click your avatar, open the **API** page, and copy or create an API key. Use that key to authenticate requests to the [RAGFlow HTTP API](./references/http_api_reference.md). --- -### How to get an API key for integration with third-party applications? +### How do I upgrade RAGFlow? -See [Acquire a RAGFlow API key](./develop/acquire_ragflow_api_key.md). +For a Go Compose deployment: + +1. Back up the database, object storage, and deployment configuration. +2. From the repository root, stop the deployment without deleting its volumes: + ```bash + docker compose --env-file docker/.env -f docker/docker-compose.yml down + ``` +3. Update the repository to the RAGFlow version you intend to deploy. +4. Set `RAGFLOW_IMAGE` in **docker/.env** to a compatible Go image. If you build from source, build `Dockerfile`, tag the image, and use that tag as `RAGFLOW_IMAGE`. +5. Pull the configured images when using registry images, then start the deployment: + ```bash + docker compose --env-file docker/.env -f docker/docker-compose.yml pull + docker compose --env-file docker/.env -f docker/docker-compose.yml up -d + ``` +6. Check the service state and logs, then call `/api/v1/system/healthz` through the configured web endpoint to verify the dependencies. + +The Go Compose entrypoint runs the standalone `ragflow_server --migrate` action before starting the server processes. Starting `ragflow_server --api`, `--admin`, or `--ingestor` directly does not run the complete migration sequence. Keep the backup until the upgrade has been verified, and do not enable `RAGFLOW_DEV_MODE` in production to bypass downgrade protection. Never add `-v` to `docker compose down` unless you intend to delete the deployment's volumes. --- -### How to upgrade RAGFlow? +### How do I switch the document engine to Infinity? -See [Upgrade RAGFlow](./administrator/upgrade_ragflow.mdx) for more information. - ---- - -### How to switch the document engine to Infinity? - -To switch your document engine from Elasticsearch to [Infinity](https://github.com/infiniflow/infinity): +To switch your Go deployment's document engine from Elasticsearch to [Infinity](https://github.com/infiniflow/infinity), run these commands from the repository root: :::danger WARNING -Switching the document engine requires rebuilding the document indexes. The following command deletes Docker volumes and existing data. Back up any data you need before continuing. +Existing document indexes are not transferred to Infinity automatically. Back up your data and plan to reprocess or reindex documents after switching engines. ::: -1. Stop all running containers and remove the existing volumes: +1. Stop the current Go Compose deployment without deleting its volumes: ```bash - $ docker compose -f docker/docker-compose.yml down -v + docker compose --env-file docker/.env -f docker/docker-compose.yml down ``` - :::caution WARNING - `-v` will delete all Docker container volumes, and the existing data will be cleared. - ::: -2. Set the following value in **docker/.env** : +2. Set the following value in **docker/.env**. Its `COMPOSE_PROFILES` setting includes `DOC_ENGINE`, so this selects the Infinity service when the deployment starts: -```env + ```env DOC_ENGINE=infinity -``` + ``` -3. Restart your Docker image: +3. Start the Go deployment and check its services: ```bash - $ docker compose -f docker/docker-compose.yml up -d + docker compose --env-file docker/.env -f docker/docker-compose.yml up -d + docker compose --env-file docker/.env -f docker/docker-compose.yml ps ``` +4. Reprocess or reindex the documents so their searchable content is written to Infinity. Verify retrieval before retiring the old Elasticsearch data. + --- ### Where are uploaded files stored in RAGFlow? -Uploaded files are stored in the configured object storage backend. MinIO is used by default, while other supported options include Amazon S3, Azure Blob Storage, Alibaba Cloud OSS, Google Cloud Storage, and OpenDAL-compatible storage. +Uploaded files are stored in the configured object storage backend. The Go backend uses MinIO by default and also supports Amazon S3, Alibaba Cloud OSS, and Google Cloud Storage. The internal bucket and object path depend on how and where the file was uploaded. Manage uploaded files through RAGFlow instead of relying on a fixed storage path. --- -### How to tune batch size for document parsing and embedding? +### How do I tune document parsing and embedding throughput? -You can control the batch size for document parsing and embedding by setting the environment variables `DOC_BULK_SIZE` and `EMBEDDING_BATCH_SIZE`. Increasing these values may improve throughput for large-scale data processing, but will also increase memory usage. Adjust them according to your hardware resources. +Document indexing processes 32 chunks per batch. The embedding request size comes from the model's `batch_size` capability, or defaults to `16` when the model does not provide one. To tune embedding requests, set `TOKENIZER_EMBEDDING_BATCH_SIZE` to a positive integer. Larger batches can use more memory and may exceed the model provider's request limit, so increase the value gradually and verify parsing on representative documents. --- @@ -637,7 +501,7 @@ If retrieval needs improvement, adjust settings such as the similarity threshold ### What needs to be reprocessed after changing the embedding model, reranker, or LLM? -- Changing the **embedding model** requires rebuilding the document indexes. RAGFlow does not normally allow you to change the embedding model after documents in the dataset have been parsed. Create a new dataset or remove the existing parsed data before using another embedding model. +- When a dataset already contains chunks, changing the **embedding model** triggers a compatibility check: RAGFlow samples existing chunks, embeds them with the candidate model, and compares the new vectors with the stored vectors. The switch is allowed when the average similarity is at least 0.9 and does not require reparsing. If the models are incompatible, remove the existing chunks and parse the documents again, or create a new dataset with the new model. - Changing the **reranker** affects only the ranking of retrieved results and does not require reparsing the documents. - Changing the **LLM** affects query understanding and answer generation and does not normally require reparsing the dataset. @@ -651,9 +515,10 @@ Check whether the content has been indexed correctly, whether the relevant chunk --- -### How to accelerate the question-answering speed of my chat assistant? +### How do I reduce my chat assistant's response latency? To reduce response latency, consider the following: + - Use a faster LLM with lower inference latency. - Reduce the number of retrieved chunks by adjusting retrieval parameters such as **Top N**. - Keep prompts concise and avoid unnecessary context. @@ -663,10 +528,12 @@ To reduce response latency, consider the following: --- -### How to accelerate the question-answering speed of my Agent? +### How do I reduce my Agent's response latency? Agent response time depends on the number of components, model calls, and external services involved in the workflow. + To improve response speed: + - Use faster models for components that do not require strong reasoning capabilities. - Reduce unnecessary LLM, retrieval, tool, and HTTP calls. - Simplify the Agent workflow and avoid excessively long execution paths. @@ -675,179 +542,171 @@ To improve response speed: - Run independent operations in parallel when the workflow supports it. - Make sure external APIs and model services used by the Agent have low latency. -### How to use MinerU to parse PDF documents? +--- -From v0.22.0 onwards, RAGFlow includes MinerU (≥ 3.3.0) as an optional PDF parser of multiple backends. Please note that RAGFlow acts only as a *remote client* for MinerU, calling the MinerU API to parse PDFs and reading the returned files. To use this feature: +### How do I use MinerU to parse PDF documents? -1. Prepare a reachable MinerU API service (FastAPI server, MinerU ≥ 3.3.0). -2. In the **.env** file or from the **Model providers** page in the UI, configure RAGFlow as a remote client to MinerU: +RAGFlow sends PDF documents to a remote MinerU service and polls for the parsed result. To use it: + +1. Prepare a reachable MinerU API service that provides the `/file_parse` and `/tasks` endpoints used by RAGFlow. +2. In **docker/.env** or on the **Model providers** page in the UI, configure RAGFlow as a remote client to MinerU: - `MINERU_APISERVER`: The MinerU API endpoint (e.g., `http://mineru-host:8886`). + - `MINERU_API_KEY`: An API key if the MinerU service requires one. - `MINERU_BACKEND`: The MinerU backend (matches current MinerU API / CLI `-b` values): - `"pipeline"` (default) - `"vlm-engine"` - `"hybrid-engine"` - `"vlm-http-client"` - `"hybrid-http-client"`. - - `MINERU_SERVER_URL`: Required when `MINERU_BACKEND` is `"vlm-http-client"` or `"hybrid-http-client"`; unused for other backends. The downstream OpenAI-compatible HTTP server (e.g., `http://vllm-host:30000`). - - `MINERU_OUTPUT_DIR`: (optional) The local directory for holding the outputs of the MinerU API service (zip/JSON) before ingestion. - - `MINERU_DELETE_OUTPUT`: Whether to delete temporary output when a temporary directory is used: - - `1`: Delete. - - `0`: Retain. 3. In the web UI, navigate to your dataset's **Configuration** page and find the **Ingestion pipeline** section: - If you decide to use a chunking method from the **Built-in** dropdown, ensure it supports PDF parsing, then select **MinerU** from the **PDF parser** dropdown. - If you use a custom ingestion pipeline instead, select **MinerU** in the **PDF parser** section of the **Parser** component. :::note -All MinerU environment variables are optional. When set, these values are used to auto-provision a MinerU OCR model for the tenant on first use. To avoid auto-provisioning, skip the environment variable settings and only configure MinerU from the **Model providers** page in the UI. +You can configure MinerU through the **Model providers** page instead of setting environment variables. Values configured for the parser take precedence over `MINERU_APISERVER`, `MINERU_API_KEY`, and `MINERU_BACKEND`. ::: -:::caution WARNING -**Upgrade note:** Older backend names (`vlm-transformers`, `vlm-vllm-engine`, `vlm-mlx-engine`, `vlm-vllm-async-engine`, `vlm-lmdeploy-engine`) are no longer accepted. After upgrading, re-select a current backend in **Model providers** (or update `MINERU_BACKEND`) and ensure your MinerU API service is ≥ 3.3.0. -::: - -:::caution WARNING -Third-party visual models are marked **Experimental**, because we have not fully tested these models for the aforementioned data extraction tasks. -::: --- -### How to configure MinerU-specific settings? +### How do I configure MinerU-specific settings? -The table below summarizes the most frequently used MinerU environment variables for remote MinerU: +Use the following environment variables when MinerU is not configured directly in the parser: | Environment variable | Description | Default | Example | | ---------------------- | ---------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- | | `MINERU_APISERVER` | URL of the MinerU API service | _unset_ | `MINERU_APISERVER=http://your-mineru-server:8886` | +| `MINERU_API_KEY` | API key, when required by MinerU | _unset_ | `MINERU_API_KEY=your-key` | | `MINERU_BACKEND` | MinerU parsing backend | `pipeline` | `MINERU_BACKEND=pipeline\|vlm-engine\|hybrid-engine\|vlm-http-client\|hybrid-http-client` | -| `MINERU_SERVER_URL` | Required for `vlm-http-client` / `hybrid-http-client`; unused otherwise | _unset_ | `MINERU_SERVER_URL=http://your-vllm-server-ip:30000` | -| `MINERU_OUTPUT_DIR` | Directory for MinerU output files | System-defined temporary directory | `MINERU_OUTPUT_DIR=/home/ragflow/mineru/output` | -| `MINERU_DELETE_OUTPUT` | Whether to delete MinerU output directory when a temp dir is used | `1` (delete temp output) | `MINERU_DELETE_OUTPUT=0` | 1. Set `MINERU_APISERVER` to point RAGFlow to your MinerU API server. -2. Set `MINERU_BACKEND` to specify a parsing backend. -3. If using `"vlm-http-client"` or `"hybrid-http-client"`, set `MINERU_SERVER_URL` to your OpenAI-compatible server's URL. MinerU API expects `backend=` and `server_url=http://:30000` in the request body. -4. Set `MINERU_OUTPUT_DIR` to specify where RAGFlow stores MinerU API output; otherwise, a system temp directory is used. -5. Set `MINERU_DELETE_OUTPUT` to `0` to keep MinerU's temp output (useful for debugging). +2. Set `MINERU_API_KEY` if your MinerU service requires authentication. +3. Set `MINERU_BACKEND` to specify the backend sent with the parse request. + +For a custom Parser component, the numeric `mineru_timeout_seconds` setup field controls how long RAGFlow polls for the result. Its default is 30 seconds; zero or a negative value also falls back to 30 seconds. :::tip NOTE -For information about other environment variables natively supported by MinerU, see [here](https://opendatalab.github.io/MinerU/usage/cli_tools/#environment-variables-description). +For other environment variables supported by MinerU itself, see the [MinerU environment variable documentation](https://opendatalab.github.io/MinerU/usage/cli_tools/#environment-variables-description). ::: --- -### How to use MinerU with a vLLM server for document parsing? +### How do I use MinerU with a vLLM server for document parsing? -RAGFlow supports MinerU's `vlm-http-client` and `hybrid-http-client` backends, enabling you to delegate document parsing tasks to a remote OpenAI-compatible server (for example vLLM) while calling MinerU via HTTP. To configure: +Set `MINERU_BACKEND` to `vlm-http-client` or `hybrid-http-client` to use a downstream OpenAI-compatible server such as vLLM. Configure the downstream server URL on the MinerU service itself. 1. Ensure a MinerU API service is reachable (for example `http://mineru-host:8886`). -2. Set up or point to an OpenAI-compatible HTTP server (for example `http://vllm-host:30000`). -3. Configure the following in your **docker/.env** file (or your shell if running from source): +2. Configure the MinerU service to use a reachable OpenAI-compatible server. +3. Configure the following in **docker/.env** (or your shell if running from source): - `MINERU_APISERVER=http://mineru-host:8886` - `MINERU_BACKEND="vlm-http-client"` (or `"hybrid-http-client"`) - - `MINERU_SERVER_URL="http://vllm-host:30000"` - MinerU API calls expect `backend=vlm-http-client` (or `hybrid-http-client`) and `server_url=http://:30000` in the request body. -4. Configure `MINERU_OUTPUT_DIR` / `MINERU_DELETE_OUTPUT` as desired to manage the returned zip/JSON before ingestion. +4. Select MinerU as the PDF parser in the dataset's ingestion settings, then check the ingestor logs if the remote parse request fails. :::tip NOTE -When using an `*-http-client` backend, the RAGFlow server requires no GPU, only network connectivity. This enables cost-effective distributed deployment with multiple RAGFlow instances sharing one remote inference server. +For these remote backends, the RAGFlow ingestor needs network access to MinerU. The downstream model service is configured and reached by MinerU. ::: -### How to use an external Docling Serve server for document parsing? +--- -RAGFlow supports Docling in two modes: +### How do I use an external Docling Serve server for document parsing? -1. **Local Docling** (existing mode): install Docling in the RAGFlow runtime (`USE_DOCLING=true`) and parse in-process. -2. **External Docling Serve** (remote mode): point RAGFlow to a Docling Serve endpoint. - -To enable remote mode, set: +The Go parser uses a remote Docling Serve endpoint. Set the endpoint in the parser configuration (`docling_server_url`) or provide it through `DOCLING_SERVER_URL` in **docker/.env**. If the service requires bearer authentication, also set `docling_api_key` in the parser configuration or provide `DOCLING_API_KEY`: ```bash DOCLING_SERVER_URL=http://your-docling-serve-host:5001 +DOCLING_API_KEY=your-api-key ``` -Behavior: +The Go parser sends PDFs to Docling Serve using `/v1/convert/source` and also tries `/v1alpha/convert/source` for older servers. It sends `DOCLING_API_KEY` as a Bearer token. If neither the parser configuration nor the environment variable supplies a URL, Docling parsing fails with a configuration error. Leave the API key unset when the service does not require authentication. -- When `DOCLING_SERVER_URL` is set, RAGFlow sends PDFs to Docling Serve using `/v1/convert/source` (and falls back to `/v1alpha/convert/source` for older servers). -- When `DOCLING_SERVER_URL` is not set, RAGFlow uses local in-process Docling. +--- -### How to use PaddleOCR for document parsing? +### How do I use PaddleOCR for document parsing? -From v0.24.0 onwards, RAGFlow includes PaddleOCR as an optional PDF parser. Please note that RAGFlow acts only as a *remote client* for PaddleOCR, calling the PaddleOCR API to parse PDFs and reading the returned files. +RAGFlow includes PaddleOCR as an optional remote PDF parser. The Go implementation supports both the asynchronous PaddleOCR Job API and a synchronous self-hosted `PaddleOCR.local` service. There are two main ways to configure and use PaddleOCR in RAGFlow: -#### 1. Using PaddleOCR Official API +#### 1. Using the official PaddleOCR API This method uses PaddleOCR's official API service with an access token. **Step 1: Configure RAGFlow** + - **Via Environment Variables:** + ```bash # In your docker/.env file: - PADDLEOCR_API_URL=https://your-paddleocr-api-endpoint + PADDLEOCR_API_URL=https://paddleocr.aistudio-app.com/api PADDLEOCR_ALGORITHM=PaddleOCR-VL PADDLEOCR_ACCESS_TOKEN=your-access-token-here ``` - **Via UI:** + - Navigate to **Model providers** page - Add a new OCR model with factory type "PaddleOCR" - Configure the following fields: - - **PaddleOCR API URL**: Your PaddleOCR API endpoint + - **PaddleOCR API URL**: The API base URL, such as `https://paddleocr.aistudio-app.com/api`, without the `/v2/ocr/jobs` suffix - **PaddleOCR Algorithm**: Select the algorithm corresponding to the API endpoint - **AI Studio Access Token**: Your access token for the PaddleOCR API **Step 2: Usage in Dataset Configuration** + - In your dataset's **Configuration** page, find the **Ingestion pipeline** section - If using built-in chunking methods that support PDF parsing, select **PaddleOCR** from the **PDF parser** dropdown - If using custom ingestion pipeline, select **PaddleOCR** in the **Parser** component **Notes:** -- To obtain the API URL, visit the [PaddleOCR official website](https://aistudio.baidu.com/paddleocr), click the **API** button, choose the example code for the specific algorithm you want to use (e.g., PaddleOCR-VL), and copy the `API_URL`. + +- When configuring the asynchronous **PaddleOCR model provider** through `PADDLEOCR_API_URL` or the **Model providers** page, use an API base URL that includes `/api`, such as `https://paddleocr.aistudio-app.com/api`, but does not include `/v2/ocr/jobs`. The provider appends `/v2/ocr/jobs`. +- When configuring the PDF parser directly with `paddleocr_base_url` in a custom Parser component or `PADDLEOCR_BASE_URL` in the environment, use the service origin without `/api`, such as `https://paddleocr.aistudio-app.com`. The direct parser appends `/api/v2/ocr/jobs`. - Access tokens can be obtained from the [AI Studio platform](https://aistudio.baidu.com/account/accessToken). - This method requires internet connectivity to reach the official PaddleOCR API. -#### 2. Using Self-Hosted PaddleOCR Service +#### 2. Using a self-hosted PaddleOCR service -This method allows you to deploy your own PaddleOCR service and use it without an access token. +For a synchronous self-hosted PaddleOCR service, add the **PaddleOCR.local** provider and configure its base URL. The current Go provider appends `/layout-parsing` to that URL. + +A self-hosted service that implements the asynchronous PaddleOCR Job API can instead use the regular **PaddleOCR** provider described above. **Step 1: Deploy PaddleOCR Service** -Follow the [PaddleOCR serving documentation](https://www.paddleocr.ai/latest/en/version3.x/inference_deployment/serving/serving.html) to deploy your own service. For layout parsing, you can use an endpoint like: -```bash -http://localhost:8080/layout-parsing +Provide a PaddleOCR service reachable from the RAGFlow container. For a synchronous `PaddleOCR.local` service running on the Docker host, an example base URL is: + +```text +http://host.docker.internal:8080 ``` +Enter the base URL without the `/layout-parsing` suffix because the Go provider appends it when sending the request. + **Step 2: Configure RAGFlow** -- **Via Environment Variables:** - ```bash - PADDLEOCR_API_URL=http://localhost:8080/layout-parsing - PADDLEOCR_ALGORITHM=PaddleOCR-VL - # No access token required for self-hosted service - ``` - **Via UI:** + - Navigate to **Model providers** page - - Add a new OCR model with factory type "PaddleOCR" + - Add a new OCR model with factory type **PaddleOCR.local** - Configure the following fields: - - **PaddleOCR API URL**: The endpoint of your deployed service - - **PaddleOCR Algorithm**: Select the algorithm corresponding to the deployed service - - **AI Studio Access Token**: Leave empty + - **PaddleOCR API URL**: The base URL of your self-hosted service + - **AI Studio Access Token**: Set a bearer token if your service requires one; otherwise leave it empty **Step 3: Usage in Dataset Configuration** + - In your dataset's **Configuration** page, find the **Ingestion pipeline** section - If using built-in chunking methods that support PDF parsing, select **PaddleOCR** from the **PDF parser** dropdown - If using custom ingestion pipeline, select **PaddleOCR** in the **Parser** component -#### Environment Variables Summary +#### Asynchronous PaddleOCR environment variable summary | Environment Variable | Description | Default | Required | |---------------------|-------------|---------|----------| -| `PADDLEOCR_API_URL` | PaddleOCR API endpoint URL | `""` | Yes, when using environment variables | +| `PADDLEOCR_API_URL` | Asynchronous model-provider base URL, including `/api` but without `/v2/ocr/jobs` | _unset_ | Yes, when configuring the model provider through environment variables | +| `PADDLEOCR_BASE_URL` | Direct PDF-parser service origin, without `/api/v2/ocr/jobs` | _unset_ | Yes, when configuring the parser directly through environment variables | | `PADDLEOCR_ALGORITHM` | Algorithm to use for parsing | `"PaddleOCR-VL"` | No | -| `PADDLEOCR_ACCESS_TOKEN` | Access token for official API | `None` | Only when using official API | +| `PADDLEOCR_ACCESS_TOKEN` | Bearer token for the PaddleOCR service | _unset_ | When the service requires authentication | -Environment variables can be used for auto-provisioning, but are not required if configuring via UI. When environment variables are set, these values are used to auto-provision a PaddleOCR model for the tenant on first use. +`PADDLEOCR_API_URL` configures and auto-provisions the asynchronous **PaddleOCR** model provider. `PADDLEOCR_BASE_URL` is the fallback used by the direct PDF parser. These variables are not required when configuring a provider through the UI and do not select **PaddleOCR.local**. +--- ### How do I use Ollama with RAGFlow for local LLM inference? @@ -855,16 +714,25 @@ RAGFlow supports Ollama as a local model provider for private, offline inference **Step 1: Start Ollama and pull a model** +Start Ollama in one terminal: + ```bash export OLLAMA_HOST=0.0.0.0 ollama serve +``` + +Binding Ollama to `0.0.0.0` makes it reachable on every network interface. Do not expose this port directly to the public internet; restrict access with a firewall or private network. + +While the service is running, pull the model in another terminal: + +```bash ollama pull llama3 ``` **Step 2: Add Ollama in RAGFlow** 1. Go to **Settings** > **Model providers** > **Ollama**. -2. Set the Base URL to `http://host.docker.internal:11434` (Docker) or `http://localhost:11434` (bare-metal). +2. Set the Base URL to `http://host.docker.internal:11434` for the provided Go Compose deployment, or `http://localhost:11434` when RAGFlow and Ollama run directly on the same host. If you use a different container setup, use an address resolvable and reachable from the RAGFlow container. 3. Enter the model name (e.g., `llama3`) and click **Save**. **Step 3: Use Ollama in your assistant** diff --git a/docs/guides/agent/agent_workflow/basic_component.md b/docs/guides/agent/agent_workflow/basic_component.md index 6f2a1171c9..c3d7bb9b5b 100644 --- a/docs/guides/agent/agent_workflow/basic_component.md +++ b/docs/guides/agent/agent_workflow/basic_component.md @@ -30,7 +30,7 @@ In `Conversational` mode, you can set the first message that the Agent says to t Example: -> Hello, I can help you query product materials, compare models, and generate installation suggestions. +> Hello, I can help you query product materials, compare models, and generate installation suggestions. > Please describe your question, or upload the files that need to be analyzed. ![Begin Component](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/begin_component_1.jpg) @@ -190,4 +190,3 @@ Retrieval parameters directly affect answer coverage, accuracy, and response tim | Similarity threshold | 0.2 | Loose recall | Questions with diverse expressions. | | Similarity threshold | 0.5 | General Q&A | Default starting value. | | Similarity threshold | 0.8 | Strict precise matching | Scenarios that require exact terminology matching. | - diff --git a/docs/guides/agent/agent_workflow/data_manipulation_components.md b/docs/guides/agent/agent_workflow/data_manipulation_components.md index ee2ec34a6d..4f34ae72f9 100644 --- a/docs/guides/agent/agent_workflow/data_manipulation_components.md +++ b/docs/guides/agent/agent_workflow/data_manipulation_components.md @@ -12,7 +12,7 @@ sidebar_custom_props: { ## Code Component The Code component executes Python or JavaScript code for complex data processing, format conversion, calculation, file generation and custom logic. -Prerequisite: The Code component depends on a secure sandbox environment. The deployment environment needs to install and enable gVisor, RAGFlow sandbox and related environment variables. Restart the service after dependency changes. +Prerequisite: The Code component requires a configured Sandbox provider. If you select the Self-Managed provider, install and enable gVisor and configure the RAGFlow sandbox environment variables. Restart the service after changing sandbox dependencies or configuration. Configuration: 1. **Input**: Define parameters passed into code; variables can be directly referenced inside scripts. diff --git a/docs/guides/agent/agent_workflow/flow_components.md b/docs/guides/agent/agent_workflow/flow_components.md index 22d7fa9db5..fd91123178 100644 --- a/docs/guides/agent/agent_workflow/flow_components.md +++ b/docs/guides/agent/agent_workflow/flow_components.md @@ -14,8 +14,7 @@ sidebar_custom_props: { Switch executes rule-based judgment and routes workflows to different downstream paths according to results. ### Configuration Method -At least one Case must be defined. Each Case can contain multiple conditions combined by AND / OR. -Supported operators: Equals, Not equal, Greater than, Greater equal, Less than, Less equal, Contains, Not contains, Starts with, Ends with, Is empty, Not empty. +At least one Case must be defined. Each Case can contain multiple conditions combined by AND / OR. Supported operators are Equals, Not equal, Greater than, Greater equal, Less than, Less equal, Contains, Not contains, Starts with, Ends with, Is empty, and Not empty. :::tip NOTE Switch is rule-based judgment for structured data and clear conditions. Categorize uses LLM-based classification for natural language intent recognition. @@ -68,7 +67,6 @@ Categorize uses LLM to judge user intent or input category and branch the workfl 6. Connect downstream components for each classification result on the canvas. ### Classification Recommendations -Use easy-to-understand category names, e.g. Product Consultation, Installation Reservation, After-sales Fault, Other Questions. -Examples improve classification stability; provide 2~3 typical samples for each category. +Use easy-to-understand category names, such as Product Consultation, Installation Reservation, After-sales Fault, and Other Questions. Examples improve classification stability; provide two or three typical samples for each category. ![Question Classification Component](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/question_classification_component.jpg) diff --git a/docs/guides/agent/agent_workflow/tool_components.md b/docs/guides/agent/agent_workflow/tool_components.md index b3f2532f16..dae9ae20dc 100644 --- a/docs/guides/agent/agent_workflow/tool_components.md +++ b/docs/guides/agent/agent_workflow/tool_components.md @@ -24,7 +24,7 @@ Tool components connect external search, databases, HTTP APIs, email sending, do ## Web Page and Information Retrieval -### Tavily Search +### Tavily Search Tavily is a web search service for LLMs. It is suitable for retrieving general web information, news, and content that needs to be limited to specific domains. Keep queries focused on a single topic and avoid overly long natural-language questions. @@ -70,7 +70,7 @@ The output usually contains search result summaries, titles, links, snippets, an ![Tavily Search](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/tavily_search.jpg) -### Tavily Extract +### Tavily Extract Tavily Extract reads the body content of one or more known URLs. A common workflow is to use Tavily Search to obtain links, then pass those links to this component to extract page content. @@ -109,7 +109,7 @@ The output contains the page body, title, URL, and extraction status. `formalize ![Tavily Extract](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/tavily_extract.jpg) -### Google +### Google Google Search obtains Google organic search results through SerpApi. It is suitable for web retrieval that requires country and language targeting. @@ -169,7 +169,7 @@ The output contains titles, links, and summaries returned by DuckDuckGo. It can ![Duckduckgo](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/duckduckgo_2.jpg) -### SearXNG +### SearXNG SearXNG is a self-hostable privacy-oriented meta-search engine. This component calls a user-provided SearXNG instance and is suitable for scenarios that need control over retrieval sources or internal search deployment. @@ -193,7 +193,7 @@ SearXNG is a self-hostable privacy-oriented meta-search engine. This component c The output contains titles, links, summaries, and source information returned by SearXNG. Before use, configure a reachable SearXNG service address and pass the system security checks. -### Keenable +### Keenable Keenable is a web search API for AI Agents. By default, it supports a public free path without a key. After configuring a key, you can increase the limit and enable low-latency realtime mode. @@ -308,7 +308,7 @@ The output contains academic retrieval entries such as paper titles, authors, ab ![Google Scholar](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/google_scholar.jpg) -### ArXiv +### ArXiv ArXiv is used to retrieve open preprints across fields such as computer science, mathematics, physics, and quantitative finance. ArXiv papers may not have undergone peer review, so mark their preprint nature when using the results. @@ -334,7 +334,7 @@ The output contains paper titles, authors, abstracts, publication times, categor ![ArXiv](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/arxiv.jpg) -### PubMed +### PubMed PubMed is used to retrieve life science and biomedical literature. The component queries through NCBI E-utilities and returns titles, authors, journals, DOIs, abstracts, and other information. @@ -360,7 +360,7 @@ The output contains medical literature titles, authors, journals, abstracts, pub ![PubMed](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/pubmed.jpg) -### BGPT +### BGPT BGPT retrieves scientific papers and returns structured evidence, including research methods, sample sizes, results, limitations, conflicts of interest, data availability, and falsifiability tips. It is suitable for evaluating scientific claims, not only for finding paper abstracts. @@ -390,7 +390,7 @@ The output contains biomedical knowledge retrieval results and summaries, which ## Data and Financial Queries -### Execute SQL +### Execute SQL Execute SQL connects to an external database and executes SQL statements. The result is formatted as text or table content. @@ -401,7 +401,7 @@ To protect system security, the database address must pass server-side security | Field | Type | Required | Default Value | Description | | --- | --- | --- | --- | --- | | sql | string | Yes | `{sys.query}` | SQL to execute. Canvas variables can be included. | -| db_type | string | Yes | mysql | Supports `mysql`, `postgres`, `mariadb`, `mssql`, `IBMDB2`, `trino`, and `oceanbase`. | +| db_type | string | Yes | mysql | Supports `mysql`, `postgres`, `mariadb`, `mssql`, `trino`, and `oceanbase`. | | database | string | Yes | Empty | Database name. Trino uses `catalog.schema` or `catalog`. | | username | string | Yes | Empty | Database account. | | host | string | Yes | Empty | Database address, which must pass server-side security checks. | @@ -417,7 +417,6 @@ To protect system security, the database address must pass server-side security | Database Type | postgres | PostgreSQL | | Database Type | mariadb | MariaDB | | Database Type | mssql | Microsoft SQL Server | -| Database Type | IBMDB2 | IBM DB2 | | Database Type | trino | Trino | | Database Type | oceanbase | OceanBase | @@ -440,7 +439,7 @@ The output contains SQL execution results, field names, and record content. You ![Execute SQL](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/execute_sql.jpg) -### Yahoo Finance +### Yahoo Finance The Yahoo Finance component queries stock quotes, company profiles, historical market data, financial statements, and news through `yfinance`, and outputs the selected content as a Markdown report. @@ -452,7 +451,7 @@ The Yahoo Finance component queries stock quotes, company profiles, historical m | info | boolean | Node configuration | true | Output company and quote information. | | history | boolean | Node configuration | false | Output historical market data. | | count | boolean | Node configuration | false | Share count switch defined by the code. | -| financials | boolean | Node configuration | false | The current implementation outputs calendar information. | +| financials | boolean | Node configuration | false | Output earnings dates and other financial calendar events returned by Yahoo Finance. | | income_stmt | boolean | Node configuration | false | Income statement switch defined by the code. | | balance_sheet | boolean | Node configuration | false | Output balance sheet and quarterly balance sheet. | | cash_flow_statement | boolean | Node configuration | false | Output cash flow statement and quarterly cash flow statement. | @@ -481,7 +480,7 @@ The Yahoo Finance component queries stock quotes, company profiles, historical m The output contains a financial query report and structured market data, which can be used by subsequent Agents to generate market overviews or indicator explanations. -### WenCai +### WenCai WenCai is used to screen financial data such as stocks, indices, funds, Hong Kong stocks, U.S. stocks, futures, and other instruments based on natural-language conditions. #### Parameter Description @@ -530,7 +529,7 @@ Before using the WenCai component, confirm that the WenCai query service is avai ### Email -The Email component sends HTML emails through SMTP and supports multiple CC addresses. The current version supports recipients, CC recipients, subject, and email body. It does not support adding attachments or BCC recipients through this component. +The Email component sends HTML emails through SMTP. Configure the recipients, CC recipients, subject, and email body in the component. #### Parameter Description @@ -574,7 +573,7 @@ The output contains sending status and error information. `success` being `true` ![Email](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/email.jpg) -### HTTP Request +### HTTP Request The HTTP Request component calls external HTTP APIs, allowing business systems, third-party services, or self-built APIs to be connected to Agent workflows. @@ -589,8 +588,7 @@ The HTTP Request component calls external HTTP APIs, allowing business systems, | timeout | integer | No | 60 | Request timeout in seconds. | | proxy | string | No | Empty | Optional HTTP/HTTPS proxy address. | | clean_html | boolean | No | false | Whether to clean HTML tags from the response. | -| datatype | string | No | json | Python request body type: `json` or `formdata`. | -| body | string | No | Empty | Raw request body supported by the Go runtime. | +| body | string | No | Empty | Raw request body. | | content_type | string | No | Empty | POST/PUT default to `application/json`. | #### Supported Values @@ -686,16 +684,12 @@ Browser is an LLM-driven browser automation component. It can access web pages, | Field | Type | Required | Default Value | Description | | --- | --- | --- | --- | --- | -| llm_id | string | Yes | Empty | Configured chat model ID used by Browser. The Go path can accept `model_id` as an alias. | -| prompts | string | Yes | `{sys.query}` | Natural-language browser task. Canvas variables are supported. The Go path can accept `prompt` as an alias. | -| max_steps | integer | No | 30 | Maximum number of browser execution steps. Effective in the Python path. The current Go Stagehand path accepts this field but does not use it during execution. | +| llm_id | string | Yes | Empty | Configured chat model ID used by Browser. | +| prompts | string | Yes | `{sys.query}` | Natural-language browser task. Canvas variables are supported. | | headless | boolean | No | true | Whether to run the browser in headless mode. | | enable_default_extensions | boolean | No | false | Whether to enable default `browser-use` extensions. | | chromium_sandbox | boolean | No | false | Whether to enable the Chromium sandbox. In Docker root environments, keep this disabled in general. | -| persist_session | boolean | No | true | Whether to reuse the browser user directory for the same node. Effective in the Python path. | | upload_sources | array/string | No | `[]` | File IDs, URLs, or upstream variable references for the browser task. | -| url | string | No | Empty | Compatibility field accepted by the current Go component. It does not participate in Stagehand execution. | -| timeout | integer | No | 0 | Compatibility field accepted by the current Go component. It does not participate in Stagehand execution. | #### Supported Values diff --git a/docs/guides/agent/ingestion_pipeline/configure_indexer_component.md b/docs/guides/agent/ingestion_pipeline/configure_indexer_component.md index 875c3f9e79..4062dd5cd9 100644 --- a/docs/guides/agent/ingestion_pipeline/configure_indexer_component.md +++ b/docs/guides/agent/ingestion_pipeline/configure_indexer_component.md @@ -10,7 +10,7 @@ sidebar_custom_props: { # Configure the Indexer Component -The **Indexer** component indexes data for optimal retrieval. It is the final step, writing processed data into search engines such as Infinity, Elasticsearch and OpenSearch. +The **Indexer** component indexes data for optimal retrieval. It is the final step, writing processed data into the configured document engine. Key configurations: diff --git a/docs/guides/agent/understand_the_canvas.md b/docs/guides/agent/understand_the_canvas.md index 404f8b47e9..29f75d1af6 100644 --- a/docs/guides/agent/understand_the_canvas.md +++ b/docs/guides/agent/understand_the_canvas.md @@ -11,8 +11,7 @@ sidebar_custom_props: { # Understand the Canvas ## Add Components -Click the plus sign next to any component on the canvas to select the next component. Common components include: -`Begin`, `Agent`, `Retrieval`, `Message`, `Await response`, `Switch`, `Iteration`, `Categorize`, `Code`, `Text processing`, `Execute SQL`, `HTTP Request`, and pipeline-related components: `Parser`, `Title chunker`, `Token chunker`, `Transformer`, `Indexer`. +Click the plus sign next to any component on the canvas to select the next component. Common components include `Begin`, `Agent`, `Retrieval`, `Message`, `Await response`, `Switch`, `Iteration`, `Categorize`, `Code`, `Text processing`, `Execute SQL`, `HTTP Request`, and pipeline-related components such as `Parser`, `Title chunker`, `Token chunker`, `Transformer`, and `Indexer`. After adding a component, click the component itself to open the configuration panel on the right. Fields in the configuration panel define input data, processing logic, output variables, and references for subsequent steps. diff --git a/docs/guides/chat/chat_configuration.md b/docs/guides/chat/chat_configuration.md index b88ce6e65c..0e27592707 100644 --- a/docs/guides/chat/chat_configuration.md +++ b/docs/guides/chat/chat_configuration.md @@ -112,12 +112,7 @@ Retrieval augmentation options further optimize queries or expand information re - **Multi-turn conversation optimization**: Uses the conversation history to optimize the current retrieval query, helping the system understand context, references, and omitted information in a continuous conversation. It is suitable for multi-turn conversations about the same topic. - **Cross-language search**: Improves retrieval across languages. When the question language differs from the language of the dataset documents, this option can improve the recall of cross-language content. -Retrieval augmentation options - +Retrieval augmentation options ![Additional retrieval augmentation settings](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/retrieval_augmentation_options_2.jpg) diff --git a/docs/guides/chat/using_chat_sessions.md b/docs/guides/chat/using_chat_sessions.md index e602b5fdc0..17e81b3f9d 100644 --- a/docs/guides/chat/using_chat_sessions.md +++ b/docs/guides/chat/using_chat_sessions.md @@ -59,11 +59,10 @@ After recording, the system converts the speech to text with the configured spee Click the paper-airplane icon next to the Chat name to open **Embed into website**. Use this configuration to integrate Chat into an external webpage or business system. -RAGFlow provides HTTP and Python APIs for integration: +RAGFlow provides an HTTP API for integration: - [Acquire a RAGFlow API key](../../develop/acquire_ragflow_api_key.md) - [HTTP API reference](../../references/http_api_reference.md) -- [Python API reference](../../references/python_api_reference.md) You can also embed the created Chat assistant in a third-party webpage with an iframe: diff --git a/docs/guides/chatchannel/channel_access_and_configuration.md b/docs/guides/chatchannel/channel_access_and_configuration.md index 1e2af16d62..1daf2f4cc6 100644 --- a/docs/guides/chatchannel/channel_access_and_configuration.md +++ b/docs/guides/chatchannel/channel_access_and_configuration.md @@ -200,12 +200,6 @@ Usage: 3. Click confirm; reopening the dialog shows the currently bound target. 4. Send a test message to the bot in WeCom and verify the reply. -### Thinking placeholder - -To keep the end user informed while a completion is still running, the WeCom channel first sends a short `🤔 开始思考...` placeholder for every accepted, non-empty inbound message, and then sends a second message with the final answer once the Chat or Agent has produced a result. Blank messages are ignored, and if a completion produces no result, no final reply is sent. This applies to both Chat and custom Agent bindings. - -The placeholder is only sent on the WeCom channel. The final reply is also cleaned up before it is sent: reasoning content (the `` blocks produced by the model) is removed, so end users only see the final answer instead of the internal thinking process. - Connection verification: After completing configuration, send a test message to the bot in WeCom to verify whether replies are received normally. diff --git a/docs/guides/data_source/data_source_configuration.md b/docs/guides/data_source/data_source_configuration.md index e26e8d941c..b518ccca71 100644 --- a/docs/guides/data_source/data_source_configuration.md +++ b/docs/guides/data_source/data_source_configuration.md @@ -67,35 +67,6 @@ The Google Drive data source is used to synchronize files or folders in Google D ![Google Drive](https://raw.githubusercontent.com/infiniflow/ragflow-docs/2ee87008723d56cb6ebf0e9c92f6ef2ad1a45254/images/Google_Drive.jpg) -## Feishu Wiki - -The Feishu Wiki data source is available with the Python backend. It recursively scans a configured Wiki subtree and imports matching downloadable `file` nodes. Native Feishu Docs, Sheets, Slides, and Bitable records are not imported directly, although the connector traverses non-file nodes to discover downloadable files below them. - -The Feishu custom app needs read-only Wiki and Drive permissions. Add the app to the target Wiki with permission to list nodes and download files. - -The connector supports this file subset: `csv`, `doc`, `docx`, `eml`, `gif`, `html`, `jpeg`, `jpg`, `json`, `md`, `mdx`, `pdf`, `png`, `ppt`, `pptx`, `tif`, `txt`, `xls`, and `xlsx`. - -Configure the following fields: - -- **Name**: A descriptive name for the connection in RAGFlow. -- **Feishu app ID** and **Feishu app secret**: Credentials for the Feishu custom app. The secret is masked in the form. -- **Wiki space ID**: The ID of the target Wiki space. -- **Wiki root node token**: The node whose descendants are scanned recursively. -- **Allowed file extensions**: An optional allow-list from the supported subset above. Leave it empty to allow the complete subset. -- **Required filename keywords**: An optional list. A filename must contain at least one configured keyword. -- **Excluded filename keywords**: An optional list. A matching filename is excluded. -- **Maximum file size (bytes)**: The largest file body the connector will accept. The default is `52428800` bytes (50 MiB). Both the declared content length and the streamed byte count are enforced. -- **Batch size**: The number of files sent to the ingestion pipeline per batch. The default is `2`; valid values are `1` through `10`. -- **Refresh interval**: The interval between periodic scans. - -Extension and filename filters are applied before a file body is downloaded. Every periodic sync scans node metadata in the subtree, but downloads only matching files whose edit time falls within the completed sync window. An empty completed scan advances that window, so the same time interval is not treated as pending again. - -File downloads retry HTTP 429 responses up to three times. The connector honors the relative delay in seconds from Feishu's `x-ogw-ratelimit-reset` response header, with a minimum wait of one second. If the header is missing or invalid, retries wait one, two, then four seconds. A requested delay above 60 seconds stops the download instead of retrying before the server's reset. See [Feishu's rate-limit guide](https://open.feishu.cn/document/server-docs/api-call-guide/frequency-control). - -Unsuccessful downloads raise a connector validation error with the HTTP status and, when available, Feishu's error code, message, and request log ID. Error-body parsing is limited to 8 KiB; diagnostic fields are length-limited and credentials are redacted. Successful file bodies, including JSON files, are imported unchanged. After retries are exhausted, the sync fails without advancing its successful window. - -Normal periodic sync does not propagate source deletions: deleting a file in Feishu does not immediately delete the imported RAGFlow document. A manual rebuild follows the existing delete-then-import behavior, so previously imported files that are no longer present or no longer match the filters can be removed during the rebuild. - ## OneDrive The OneDrive data source is used to synchronize files in OneDrive or OneDrive for Business to a RAGFlow knowledge base. After configuration, personal or department cloud files can be queried in a unified way. @@ -437,11 +408,7 @@ The Azure DevOps data source is used to synchronize Azure Repos source files and - **Repositories**: Comma separated repositories, used when indexing by repository. Use `project/repo` to disambiguate repositories that share a name across projects. - **Content Types**: Choose whether to index source files, pull requests, or both. -Pull request descriptions are re-fetched individually when they reach the 400 -character limit the list endpoint truncates at, so long descriptions are indexed -in full. Completed and abandoned pull requests are filtered by their close date; -active ones are always re-indexed, because Azure DevOps exposes no dependable -"last updated" timestamp for them. +Pull request descriptions are re-fetched individually when they reach the 400 character limit imposed by the list endpoint, so long descriptions are indexed in full. Completed and abandoned pull requests are filtered by their close date; active ones are always re-indexed because Azure DevOps exposes no dependable "last updated" timestamp for them. - **Sync deleted files**: After this is enabled, content deleted from the external system is removed from the knowledge base index. Build output and vendored directories such as `node_modules`, `bin`, `obj`, `dist`, and `vendor` are skipped, along with binary files and files larger than 1 MB. @@ -494,7 +461,7 @@ The Gmail data source is used to synchronize Gmail email content to a RAGFlow kn **Permission requirements**: Google OAuth authorization must have read permissions for the target mailbox emails. -**Account version requirements**: The current interface includes a primary administrator email and OAuth JSON, which is more suitable for Google Workspace administrators or organization mailbox synchronization. Ordinary personal Gmail is recommended only after the actual authorization flow supports it. +**Account and authorization requirements**: To synchronize a Google Workspace domain, enter a Workspace administrator account as the primary administrator email and provide OAuth credentials authorized for the required Gmail and Admin Directory read-only scopes. To synchronize one Gmail mailbox, enter that mailbox address as the primary administrator email and provide OAuth token JSON containing a refresh token, client ID, and client secret for the same account. When the account does not expose a Workspace directory, the connector synchronizes the primary mailbox only. **Configuration parameters**: @@ -748,7 +715,7 @@ The Sitemap data source is used to synchronize the web pages listed in a public - **Batch size**: The number of pages fetched and sent to RAGFlow per batch. - **Sync deleted files**: After this is enabled, pages removed from the sitemap are removed from the knowledge base index. -Every request goes through the SSRF guard with the resolved address pinned for the duration of the request, response bodies are capped at 64 MB, and at most 1000 sitemap documents are fetched per sync (each sitemap URL once). HTML pages are converted to Markdown with the same boilerplate removal as the other web connectors (`WEB_CONNECTOR_IGNORED_ELEMENTS`: navigation, footer, aside, scripts and styles by default) and stored as `.md` documents. URLs served with `Content-Type: application/pdf` are stored as `.pdf` documents and processed by the regular PDF pipeline. Each document keeps the page URL, the sitemap URL, and, for discovered PDFs, the parent page URL in its metadata. +Every request goes through the SSRF guard with the resolved address pinned for the duration of the request, response bodies are capped at 64 MB, and at most 1000 sitemap documents are fetched per sync (each sitemap URL once). HTML pages are converted to Markdown and stored as `.md` documents; during conversion, `script`, `style`, `noscript`, `nav`, `header`, `footer`, `aside`, `form`, `iframe`, and `svg` elements are removed. URLs served with `Content-Type: application/pdf` are stored as `.pdf` documents and processed by the regular PDF pipeline. Each document keeps the page URL, the sitemap URL, and, for discovered PDFs, the parent page URL in its metadata. Incremental syncs rely on the `` element: only pages whose `lastmod` falls inside the sync window are fetched again, and pages without `lastmod` are only fetched by a full sync. Every document also carries a content fingerprint, so a page that is fetched again but has not changed is skipped instead of being re-indexed. diff --git a/docs/guides/data_source/overview_and_page_management.md b/docs/guides/data_source/overview_and_page_management.md index d3e78600b0..1210db119a 100644 --- a/docs/guides/data_source/overview_and_page_management.md +++ b/docs/guides/data_source/overview_and_page_management.md @@ -58,6 +58,7 @@ Common fields on the settings page include: - **Refresh interval**: The interval at which RAGFlow checks the external system for newly added or updated content. - **Cleanup interval**: The interval at which RAGFlow checks the external system for deleted content. It takes effect only when sync deleted files is enabled. - **Timeout**: The maximum time that a single connection or synchronization task is allowed to wait. +- **Test connection**: Verifies whether the current configuration can successfully connect to the external data source. It is recommended to test the connection before saving the configuration or starting a sync task. After completing the modification, click **Save**. The new configuration is used for subsequent synchronization tasks. Content that has already been synchronized to the knowledge base is gradually updated according to the next synchronization or cleanup task. diff --git a/docs/guides/dataset/best_practices/accelerate_doc_indexing.mdx b/docs/guides/dataset/best_practices/accelerate_doc_indexing.mdx index 9b48b33b9b..e8ec27d62a 100644 --- a/docs/guides/dataset/best_practices/accelerate_doc_indexing.mdx +++ b/docs/guides/dataset/best_practices/accelerate_doc_indexing.mdx @@ -17,4 +17,4 @@ Please note that some of your settings may consume a significant amount of time. - On the configuration page of your dataset, switch off **Use RAPTOR to enhance retrieval**. - Extracting knowledge graph (GraphRAG) is time-consuming. - Disable **Auto-keyword** and **Auto-question** on the configuration page of your dataset, as both depend on the LLM. -- **v0.17.0+:** If all PDFs in your dataset are plain text and do not require GPU-intensive processes like OCR (Optical Character Recognition), TSR (Table Structure Recognition), or DLA (Document Layout Analysis), you can choose **Naive** over **DeepDoc** or other time-consuming large model options in the **Document parser** dropdown. This will substantially reduce document parsing time. +- **v0.17.0+:** If all PDFs in your dataset are plain text and do not require compute-intensive processes like OCR (Optical Character Recognition), TSR (Table Structure Recognition), or DLA (Document Layout Analysis), you can choose **Naive** over **DeepDoc** or other time-consuming large model options in the **Document parser** dropdown. This will substantially reduce document parsing time. In the RAGFlow open-source 1.0 release, DeepDoc performs these operations with CPU inference. diff --git a/docs/guides/dataset/configuration.md b/docs/guides/dataset/configuration.md index e8ea2a24b7..3a672ab7ca 100644 --- a/docs/guides/dataset/configuration.md +++ b/docs/guides/dataset/configuration.md @@ -42,69 +42,271 @@ The following built-in parsing methods are available: - **Presentation**: Designed for presentations in PDF and PPTX formats. Each page or slide is typically treated as an individual chunk. - **One**: Treats the entire document as a single chunk. This method is suitable for relatively short documents when the complete context needs to be preserved. - **Tag**: Used to create a tag set. A dataset using this method provides tags for chunks and queries in other datasets and does not directly participate in the RAG retrieval process. +- **Audio**: An audio parsing method for audio files such as WAV, MP3, AAC, FLAC, and OGG. It uses an ASR model to transcribe audio into text and then generates chunks from the transcription. +- **Email**: An email parsing method for email files such as EML and MSG. It extracts content including the sender, recipients, subject, body, and attachments, and generates chunks from the extracted content. -> **Tip:** On the built-in parsing configuration page, click **Built-in pipeline introduction** on the right to view the supported file formats, detailed chunking rules, and examples for each parsing method. +> **Tip:** On the built-in parsing configuration page, click **View built-in parser details** on the right to view the supported file formats, detailed chunking rules, and examples for each parsing method. Selection suggestion: choose the parsing method based on the form of the material itself. Use **General** first for regular documents; use **Table** first for tabular materials; choose the corresponding method for Q&A collections, manuals, papers, images, audio, and emails to reduce later chunk adjustment costs. -### Chunk and Parsing Configuration +### Build-in Parsing Configuration -After selecting a **Built-in** parsing method, you can further configure document parsing, chunk splitting, and content enhancement parameters. Reasonable configuration helps improve the accuracy and recall of later retrieval. +After selecting a built-in template parsing method, you can further configure document parsing, chunking, and content enhancement. Appropriate settings can improve the accuracy and recall of subsequent retrieval. -Different built-in methods display different configuration items. Use the current interface as the source of truth. +Different built-in methods display different configuration options. Refer to the options shown in your current interface. -#### Document Parsing Configuration +#### Parser Configuration -- **PDF parser**: Specifies the parser used when parsing PDF documents. Different parsers differ in text recognition, table structure recognition, layout analysis, processing speed, and other aspects. Choose one based on the content type and parsing requirements of the PDF. The system provides the following PDF parsers by default: - - **DeepDoc**: The default PDF parser in RAGFlow. It can perform OCR, table structure recognition (TSR), document layout understanding (DLR), and other tasks. It is suitable for PDFs that contain complex layouts, images, scanned content, or tables. Because additional document analysis is required, parsing may take relatively longer. - - **Naive**: Suitable for PDFs mainly composed of plain text. This method skips OCR, TSR, DLR, and other processing, reducing unnecessary parsing overhead. If a PDF contains scanned pages, complex layouts, or tables, this method is not recommended. - - **Docling**: An open-source document processing tool that can parse documents such as PDFs and extract structured content. - - **TCADPParser**: Tencent's open-source document parsing tool, which can be used for PDF content parsing. +Parser configuration determines how different types of content are processed. You can configure parsing parameters for each format according to the document structure, layout complexity, and extraction requirements. This helps improve content extraction and the accuracy of subsequent chunk generation. -In addition to the built-in parsers above, you can also use a vision-language model (VLM) that supports PDF parsing. To use a third-party vision model to parse PDFs, first configure the default VLM under **Model Providers > Set default model**. After configuration, select the corresponding model from the **PDF parser** drop-down list. +##### PDF Parsing -Usually, some vision models whose names contain identifiers such as **VL** or **V** support PDF parsing. For documents with complex layouts or mixed text and images, a more capable vision model may produce better parsing results, but it also incurs additional model calls and token consumption. The specific support and parsing effect depend on the model used. +Configure how PDF documents are parsed. You can select a parsing method based on the PDF layout and set options such as page ranges and vision models. -#### Chunk Splitting Configuration +- **Multi-column layout recognition:** Recognizes PDFs with complex layouts, such as two-column or multi-column pages. When enabled, the parser identifies text regions and extracts content in a suitable reading order. This is useful for papers, journals, reports, and other multi-column documents. +- **Remove original table of contents:** Removes the PDF's existing table of contents during parsing so that its text does not enter subsequent chunks or search results as body content. +- **Remove headers and footers:** Identifies and removes repeated page headers and footers to reduce irrelevant content in the knowledge base. +- **Parsing method:** Selects a parser for PDF or table content. Parsing methods differ in text recognition, layout analysis, table recognition, and handling of complex documents. Built-in methods include: + - **DeepDOC:** RAGFlow's default document parser. It performs OCR, table structure recognition, and document layout analysis. It is suitable for PDFs containing complex layouts, images, scanned content, or tables. + - **Naive:** Suitable for PDFs that primarily contain plain text. It reduces OCR, table recognition, and complex layout analysis, making it faster for simple text-based PDFs. + - **Docling:** An open-source document parsing tool that can parse PDFs and other documents and extract structured content. + - **OpenDataLoader:** Extracts text, layout, and structured information from documents. It can serve as an alternative to other built-in parsing methods. + - **TCADP Parser:** An open-source parser from Tencent that can parse PDF content. + - **MonkeyOCRv2:** A vision-based parsing method that combines OCR and visual understanding to process scanned documents, complex layouts, and mixed text and images. -The following configurations are mainly used for built-in methods that need to split text according to specified rules, such as **General**. + In addition to these built-in methods, you can select an external model service already configured in the system. For example, a vision-language model (VLM) or another model with document understanding capabilities connected through a model provider can be used to parse PDFs or tables. -- **Recommended chunk size**: Sets the recommended target size when generating chunks. Smaller chunks can provide more fine-grained retrieval results but may lack context. Larger chunks can preserve more context, but retrieval result granularity is relatively coarse. -- **Delimiter for text**: Sets the delimiter used for text splitting. The system splits text based on the delimiter and chunk size. It is recommended to set an appropriate delimiter based on the original paragraph and line-break structure to preserve semantic completeness as much as possible. -- **Overlapped percent (%)**: Sets the content overlap ratio between adjacent chunks. Increasing overlap appropriately can reduce context loss caused by split boundaries, but an overly high overlap ratio increases repeated content. -- **Child chunk are used for retrieval**: Controls whether finer-grained child chunks participate in retrieval. This is suitable for long documents where fine-grained recall needs to be improved. + External models are often better suited to complex layouts, scanned documents, images, borderless tables, and mixed text and images. However, they incur additional model calls and token usage. The available models depend on the configured model providers and their capabilities. +- **Page range:** Specifies which PDF pages to parse. You can set a start and end page and add multiple page ranges to avoid processing unnecessary content. +- **Disable vision model:** Controls whether a VLM is used during PDF parsing. When this option is enabled, no vision model assists with parsing. When disabled, a vision model can help interpret complex layouts or content combining text and images. +- **Model:** Selects the vision model to use when PDF parsing requires one. A more capable vision model may provide a more complete understanding of complex layouts and visual content. Parsing quality and token usage depend on the selected model. -#### Page and Multimodal Content Configuration +##### Table Parsing -- **Page Index**: Controls whether Page Index-related capabilities are used to process document page information. -- **Image & table context window**: Sets the context range between images or tables and surrounding text. Increasing this value appropriately can preserve more related context when processing images or tables. +Configure how tables in documents are parsed. The system can use a built-in parser or a vision model to recognize table structure and extract text and cell information. -#### Content Enhancement Configuration +- **Parsing method:** Selects a parser or model for tables. Methods differ in table structure recognition, cell content extraction, and handling of complex layouts. Built-in methods include: + - **DeepDOC:** RAGFlow's built-in document parser. It recognizes table structure and extracts cell content, making it suitable for most standard tables. + - **TCADP Parser:** An open-source parser from Tencent that can recognize and parse tables in documents. -Some built-in methods provide the following content enhancement configurations, such as **General**, **Manual**, **Paper**, **Book**, and **Laws**. + You can also select an external model already configured in the system. Available models are grouped by model provider in the drop-down list. For complex tables, borderless tables, merged rows or columns, or tables that require visual interpretation, choose an external model with vision or document understanding capabilities as needed. External models may incur additional model calls and token usage. +- **Disable vision model:** Controls whether a vision model is used for table parsing. Built-in parsers may be sufficient for regular tables with clear boundaries. A vision model can help with complex or borderless tables. +- **Model:** Selects the vision model used for table parsing when vision support is enabled. Models may differ in their understanding of table structure and complex layouts, as well as in token usage. -- **Auto metadata**: Controls whether metadata is generated automatically. After it is enabled, the generation method for metadata can be further configured through **Settings**. -- **Auto-keyword**: Sets the number of keywords automatically generated for chunks to supplement chunk semantic information. -- **Auto-question**: Sets the number of questions automatically generated based on chunk content to supplement query expressions that may match the current chunk. +For ordinary text-based PDFs, consider starting with a built-in parser. For scanned documents, multi-column layouts, complex tables, and mixed text and images, a vision model may improve parsing quality. Because vision models incur additional calls and token usage, enable them according to the document type. -#### Table Parsing Configuration +##### Image Parsing -When **Table** is selected, the interface provides a dedicated **Column mode** configuration used to control how table columns participate in generating chunk content and metadata. +Configure how image files are parsed so that text or visual content can be converted into text for subsequent chunking and retrieval. -- **Auto**: The system processes table columns according to the default rules. By default, all columns are included in the chunk text and are also saved as metadata. -- **Manual**: Manually configures the table columns that need to participate in processing. This configuration mainly targets structured table data and differs from chunk splitting configuration for ordinary text-based built-in methods. +- **Parsing method:** Selects how image files are processed. + - **OCR:** Uses optical character recognition to extract text from images. It is suitable for screenshots, scans, photographs, and other images containing readable text. + - **External model:** Uses a configured model with visual understanding capabilities. Compared with traditional OCR, such a model can recognize text and interpret layouts, charts, objects, and relationships between text and images. External models are grouped by model provider in the drop-down list. The available models depend on the configured providers and model capabilities. -#### Other Format Processing Configuration +For images that mainly contain clear text, consider starting with OCR. For charts, complex layouts, interface screenshots, or content that requires visual understanding, select an external vision model. External models may incur additional model calls and token usage. -Some built-in methods may also provide configuration for specific file formats, for example: +Parsing quality also depends on image clarity, text size, layout, and overall image quality. -- **Excel to HTML**: Controls whether Excel content is converted into HTML for processing, preserving table structure information. +##### Markdown Parsing -Different built-in methods use different parsing logic, so not all configuration items appear at the same time. After selecting a built-in method, configure only the parameters displayed in the current interface. In general, for ordinary text documents, focus on chunk splitting parameters such as **Recommended chunk size**, **Delimiter for text**, and **Overlapped percent (%)**. For PDFs, papers, books, manuals, or legal documents, focus on **PDF parser** and the corresponding content enhancement configuration. For table data, focus on **Column mode**. When you need to further enrich retrieval information, use content enhancement features such as **Auto metadata**, **Auto-keyword**, and **Auto-question** according to actual requirements. +Parse Markdown documents while preserving their text and basic structure for subsequent chunking. -After configuration is complete, click **Save** to save the settings. When documents are parsed later, the system processes them according to the currently selected built-in method and its configuration. +- **Remove original table of contents:** Removes an existing table of contents during parsing to avoid repeating title links and body content. +- **Disable vision model:** Controls whether a vision model assists with Markdown parsing. When enabled, no vision model is used. When disabled, the selected vision model can process images or other content in the Markdown document that requires visual understanding. +- **Model:** Selects the vision model when one is needed. Available models depend on the configured model providers and their capabilities. External models may incur additional model calls and token usage. -### Pipeline: Custom Parsing +##### HTML Parsing + +Parse HTML documents to extract useful text and structured content while filtering page elements that need not be included in knowledge base retrieval. + +- **Remove original table of contents:** Removes an existing table of contents or navigation list to reduce duplicated content. +- **Remove headers and footers:** Attempts to remove repeated headers and footers, reducing the effect of navigation and copyright information on chunking and retrieval. + +For HTML files saved or exported from websites, decide whether to enable these options based on the page structure. Keep headers, footers, or tables of contents when they contain information you need. + +##### DOC Parsing + +Parse Word documents in `.doc` format. You can choose whether to remove the table of contents, headers, and footers, and whether to use an external vision model for complex content. + +- **Remove original table of contents:** Removes the existing table of contents to reduce duplication between the contents list and the document body. +- **Remove headers and footers:** Attempts to remove repeated headers and footers so that page numbers, document titles, and copyright information do not repeatedly appear in chunks. +- **Disable vision model:** Controls whether an external vision model assists with DOC parsing. When enabled, no vision model is called. When disabled, you can select a configured external model to further parse images, complex layouts, or other visual content. +- **Model:** Selects an external model to assist with DOC parsing. Only models already configured in the system are available. The options depend on the connected providers and model capabilities. External models may incur additional model calls and token usage. + +##### DOCX Parsing + +Parse Word documents in `.docx` format. You can choose whether to remove the table of contents, headers, and footers, and whether to use an external vision model for complex content. + +- **Remove original table of contents:** Removes the existing table of contents to avoid duplicating headings and body content. +- **Remove headers and footers:** Removes repeated headers and footers to reduce irrelevant information in subsequent chunks and search results. +- **Disable vision model:** Controls whether an external vision model is used for DOCX parsing. When enabled, no vision model is used. When disabled, an external model can help interpret images, complex layouts, and other visual content. +- **Model:** Selects an external model to assist with DOCX parsing. This option only lists configured external models; it does not offer built-in parsing methods such as DeepDOC, Naive, or Docling. The available models depend on the configured model providers. + +##### PPTX Parsing + +Configure how PPTX files are parsed. Text, tables, images, and other slide content are extracted and converted into text for subsequent chunking and retrieval. + +- **Parsing method:** Selects how PPTX files are processed. + - **DeepDOC:** RAGFlow's built-in document parser. It extracts text, tables, and layout content from slides and is suitable for most standard PPTX files. + - **TCADP Parser:** An open-source parser from Tencent that can extract text and structured content from PPTX files. + - **External model:** Uses a configured model with document or visual understanding capabilities. External models are grouped by model provider in the drop-down list. Availability depends on the configured providers and model capabilities. + +For PPTX files mainly containing text and standard tables, consider starting with DeepDOC or TCADP Parser. For complex layouts, mixed text and images, many images, or content requiring visual interpretation, choose a capable external model. External models may incur additional model calls and token usage. + +Parsing quality depends on slide layout, image quality, content complexity, and the selected method. + +##### Video Parsing + +Configure how video files are parsed. An external model recognizes and interprets speech, visuals, and other content, then converts the results into text for subsequent chunking and retrieval. + +Select a configured external model with video or multimodal understanding capabilities. Video parsing supports only external models already configured in the system. Such a model can analyze video frames, visible text, speech, and contextual information to generate corresponding text. + +Available models depend on the configured providers and their capabilities. Long videos, frequent scene changes, and complex content may increase processing time and model usage. External models may incur additional calls and token usage. Parsing quality depends on video quality, audio and visual clarity, content complexity, and the selected model. + +##### Audio Parsing + +Configure how audio files are parsed. An external model transcribes speech into text for subsequent chunking and retrieval. + +Select a configured external model with automatic speech recognition (ASR) capabilities. Audio parsing supports only external models already configured in the system. + +Available models depend on the configured providers and their capabilities. Models may differ in language support, accent recognition, handling of multiple speakers or background noise, and long-audio transcription. + +External models may incur additional calls and token usage. Transcription quality depends on recording clarity, background noise, speaking speed, language, and accent. + +#### Chunker Configuration + +##### General Chunker + +Configure general chunking of parsed content. The system splits content into chunks based on the target chunk size, overlap ratio, and delimiters. It can also add context to tables and images or use parent-child chunks to improve retrieval precision. + +- **Recommended chunk size:** Sets the target size of each chunk in tokens. The default is **512**. The system attempts to combine adjacent content to reach this size, but the value is a target rather than a strict limit. An indivisible content segment that already exceeds the target may remain as one chunk. +- **Overlap ratio (%):** Sets how much content adjacent chunks share. When overlap is enabled, content from the end of one chunk is copied to the start of the next. This reduces context loss at chunk boundaries and improves semantic continuity. Set it to **0** for no overlap. +- **Table context window:** Sets the amount of preceding and following context, in tokens, attached to a table chunk. More context can preserve the relationship between a table and the surrounding text. Set it to **0** to add no extra table context. +- **Image context window:** Sets the amount of preceding and following context, in tokens, attached to an image chunk. This is useful when nearby text is needed to understand an image. Set it to **0** to add no extra image context. +- **Delimiters:** Sets the separators used to split text, such as the newline character `\n`, periods, question marks, exclamation marks, and semicolons. + - **Split by delimiter:** Text is first split at the configured delimiters. The system then combines adjacent segments according to the recommended chunk size to form chunks of suitable size while preserving meaning where possible. + - **Split positions:** Displays all configured delimiters so you can see which boundaries are used for chunking. + - **Add:** Adds a custom delimiter. You can use characters that mark meaningful boundaries in your documents, such as heading or paragraph markers. +- **Use sub-chunks for retrieval:** Enables parent-child chunking. The system creates smaller child chunks from larger parent chunks and uses the child chunks for retrieval. When a relevant child chunk matches, its parent chunk can provide more complete context. + +For ordinary documents, start with the default **512-token** chunk size and choose delimiters that match the document structure. Increase overlap when context frequently crosses chunk boundaries. Configure context windows for documents with many tables or images. Enable sub-chunks when you need precise retrieval while retaining broader context. + +##### Title Chunker + +The Title Chunker identifies document structure from heading levels and organizes content into chunks. It provides two modes: **Hierarchy** and **Group**. + +###### Hierarchy + +Hierarchy builds a document tree from heading levels and generates independent chunks. Each chunk retains its full parent heading path. For example, a chunk may contain `Part 1 > Chapter 3 > Section 2` followed by the body text. This helps identify the chunk's location even when it is retrieved outside the original document. + +Hierarchy is suitable for documents with relatively independent sections and meaningful heading structures, such as legal provisions, regulations, contracts, and technical specifications. + +- **Chunk token limit:** Sets the maximum token count for a chunk. Content exceeding the limit is split further to avoid overly large chunks. +- **Heading level:** Selects the heading level used to generate chunks, such as **H3**. The system identifies H1, H2, H3, and other levels according to the configured heading rules, then organizes and splits content at the selected level. +- **Separate parent heading content:** Controls whether body content directly under a parent heading is handled separately. Enabling it prevents the parent section's own content from being mixed with its child sections in one chunk. +- **Set first chunk as global context:** Uses the document's first chunk as document-level background information for subsequent chunks. +- **Rules:** Define how headings are recognized in different documents. Each rule can contain regular expressions for H1 through H5. + - **Regular expressions for H1–H5:** Identify headings at each level. For example, expressions can match Markdown headings such as `#`, `##`, and `###`; numbered Chinese headings; or English headings such as `PART`, `Chapter`, `Section`, and `Article`. + - **Add regular expression:** Adds a heading level and its expression to the current rule. + - **Add rule:** Adds another set of heading recognition rules for a different language, numbering system, or document format. + +Hierarchy works well when the location of content within the document matters. Its chunks retain the relevant heading relationships so that retrieval results can include both the body text and its section path. + +###### Group + +Group creates flatter chunks at a selected heading level and combines adjacent small sections to preserve semantic continuity. Unlike Hierarchy, Group does not add the full parent heading path to every chunk. It emphasizes continuity between nearby content. + +Group is suitable for books, user manuals, reports, articles, and other documents whose neighboring paragraphs or sections depend on one another. + +- **Chunk token limit:** Sets the maximum token count for a chunk. The system combines adjacent sections based on heading structure while attempting to keep chunks within this limit. +- **Heading level:** Sets the heading level used to group and split content. + - **Automatic:** Lets the system choose an appropriate level based on the detected document structure. + - **H1, H2, H3, and other levels:** Select a specific level according to the document structure to control where content is grouped. +- **Rules:** Define how headings are recognized. As with Hierarchy, you can use multiple sets of regular expressions for different formats, languages, and numbering systems. + - **Regular expressions for H1–H5:** Define matching patterns for each heading level. + - **Add regular expression:** Adds another heading-level expression to the current rule. + - **Add rule:** Adds another heading recognition rule for a different document structure. + +Group works well when continuity between nearby sections matters. It combines adjacent sections at heading boundaries to keep chunks meaningful without adding the full parent heading path to each one. + +#### Extractor Configuration + +The Extractor adds information to chunks after chunking. It can use a model to generate keywords, questions, tags, contextual summaries, and metadata. These additions can improve subsequent retrieval and question answering. + +##### Model + +Select the model used by the Extractor. Automatic keywords, automatic questions, augmented context, and metadata that requires model generation call the selected model. Available models depend on the configured providers and their capabilities. + +##### Automatic Keywords + +Automatically extract keywords or phrases that represent the main content of each chunk. + +- **Number of automatic keywords:** Sets how many keywords are generated for each chunk. Set it to **0** to disable keyword extraction. +- **System prompt:** Sets the instruction sent to the model. The default prompt asks the model to analyze the text and extract the `{{ topn }}` most important keywords or phrases. You can adapt the prompt to specify keyword types, output language, or format. + +Generated keywords add semantic information to chunks and can help with retrieval and content matching. + +##### Automatic Questions + +Automatically generate questions that each chunk can answer. This adds query-like expressions to the content. + +- **Number of automatic questions:** Sets how many questions are generated for each chunk. Set it to **0** to disable question generation. +- **System prompt:** Sets the instruction sent to the model. The default prompt asks the model to understand the text and generate `{{ topn }}` questions related to its main content. + +Generated questions should cover important information in the chunk without repeating the same meaning. They can make document content easier to match with users' natural-language questions. + +##### Tags + +Extract or match tags for chunks using a prepared tag file. Tags can classify knowledge content and add semantic information. + +- **Number of automatically extracted tags:** Sets how many tags are extracted for each chunk. Set it to **0** to disable automatic tag extraction. +- **Tag file:** Selects the file used for tag extraction. The system matches or generates tags for chunks based on the selected tag collection. + +Prepare a tag file suitable for the knowledge base before using this feature. A well-designed tag system can support content classification, retrieval, and filtering. + +##### Augmented Context + +Generate a concise contextual summary for each chunk and add it as supplementary information. This helps a chunk retain essential background when viewed separately from its source document. + +- **Enable augmented context:** Calls the selected model to generate contextual information from the chunk. +- **System prompt:** Sets the instruction sent to the model. The default prompt asks for a concise summary faithful to the source content, without introducing information absent from it. + +Augmented context is useful when a chunk may lose important background after splitting. For example, a chunk containing only a short passage can gain a summary of its subject and context, helping retrieval and model understanding. + +Enabling this feature increases model calls and token usage. + +##### Metadata + +Add structured metadata to parsed content. Metadata describes document or chunk attributes and can be used for retrieval, filtering, and content management. + +- **Enable metadata:** Extracts or generates metadata according to the configured fields. +- **Settings:** Opens the metadata generation settings, where you configure the fields to extract or generate. + +Metadata generation settings provide the following options: + +- **Generate:** Define metadata fields to generate. Add fields and configure their descriptions, types, and values. The system generates metadata based on these settings. +- **Built-in parser template:** Use structured information already provided during parsing as a metadata source, without defining the same information again. +- **Add:** Add a metadata field with a name, description, type, and value according to your needs. + +For example, you can add fields for document type, department, author, subject, date, or business category. Well-configured metadata lets you narrow subsequent searches with metadata conditions. Metadata generated by a model may incur additional model calls and token usage. + +#### Indexer Configuration + +Configure how chunks are indexed and written to the retrieval engine. You can use full-text search, vector search, or both, and specify which content field is indexed. The Indexer uses the embedding model configured for the knowledge base; you do not need to select one here. + +- **Search methods:** Select one or more ways to index and retrieve chunks. + - **Embedding:** Creates vector representations and a vector index for semantic retrieval. A relevant chunk may be retrieved even when the query does not use the same words as the source text. + - **Full-text:** Creates a full-text index for keyword matching. This is useful for product codes, names, technical terms, code, and other content requiring exact matches. + - **Embedding + Full-text:** Creates both vector and full-text indexes to support semantic and keyword matching. +- **Filename embedding weight:** Sets the filename's weight in the vector representation. The filename contributes semantic information alongside the chunk content. A higher value gives it more influence. Increase the weight when filenames clearly express document topics; decrease it when filenames are random identifiers or have little meaning. +- **Fields:** Specifies the content used for indexing and retrieval. Available fields are **Processed text**, **Questions**, and **Augmented context**. + - **Processed text:** Indexes the chunk body produced by the Parser, Chunker, and other preceding steps. This is the most direct method and the default selection. + - **Questions:** Indexes questions generated by the Extractor's Automatic Questions feature. A user's question can then match a pre-generated question, which is useful for question-answering knowledge bases. Configure automatic question extraction before using this field. + - **Augmented context:** Indexes context generated by the Extractor instead of relying only on the original chunk content. This is useful when chunks need additional background for effective retrieval. + +For most knowledge bases, you can enable both **Embedding** and **Full-text** and index **Processed text**. If you have enabled Automatic Questions or Augmented Context, consider indexing **Questions** or **Augmented context** according to the types of queries you expect. + +### Custom Ingestion Pipeline **Pipeline** means using a custom **Ingestion Pipeline** as the dataset's parsing method. It is suitable for scenarios that require custom document processing logic or complex processing flows. diff --git a/docs/guides/dataset/dataset_overview.md b/docs/guides/dataset/dataset_overview.md index 9abd392ecf..7359cfda29 100644 --- a/docs/guides/dataset/dataset_overview.md +++ b/docs/guides/dataset/dataset_overview.md @@ -16,17 +16,17 @@ A dataset is the workspace in RAGFlow that carries knowledge sources and retriev In terms of responsibility, a dataset is more than a "folder". It converts raw documents into retrievable chunks, stores the enabled status of documents and chunks, maintains metadata, and provides foundational data for knowledge artifacts and log tracing. -## Basic Workflow +## Basic Information -The following briefly introduces the basic dataset workflow and helps you quickly understand the overall process from creating a dataset to testing retrieval results. The specific operations, configuration items, and feature descriptions involved in each step are described in detail in later sections. +The configuration page allows you to manage the core settings of a knowledge base. Basic information includes the name, language, avatar, description, permissions, embedding model, PageRank, and tag sets. -1. Create a dataset and select an embedding model and parsing method. -2. Complete dataset configuration under **Configuration**. -3. Upload or add documents under **Document Management**. -4. Parse documents and generate chunks. -5. Check and adjust chunks and metadata. -6. Use **Retrieval Testing** to test retrieval results. -7. Adjust parsing or retrieval configuration based on the test results. +- **Name**: The name of the knowledge base. It can be changed after creation and is displayed on knowledge base cards and detail page headers. +- **Language**: The primary language of the knowledge base. This setting affects the language assumptions used during parsing and model processing. +- **Avatar**: The avatar of the knowledge base. Image uploads are supported, with a maximum file size of 4 MB. +- **Description**: A description of the knowledge base, used to explain its data scope, business purpose, or maintenance information. +- **Permissions**: Controls access to the knowledge base and the scope of allowed operations. +- **Embedding model**: The model used to vectorize chunks. Changing the embedding model after content has already been parsed usually affects existing indexes and should be done with caution. +- **PageRank**: Sets the PageRank score for the knowledge base. During retrieval, this score is added to the hybrid similarity score of matching chunks from the knowledge base, increasing their ranking weight. This is useful when searching across multiple knowledge bases and you want to prioritize content from a specific knowledge base. ## Dataset Page Overview diff --git a/docs/guides/dataset/files_dataset_document_management.md b/docs/guides/dataset/files_dataset_document_management.md index 590a14f5c0..cc95c84c1b 100644 --- a/docs/guides/dataset/files_dataset_document_management.md +++ b/docs/guides/dataset/files_dataset_document_management.md @@ -54,9 +54,7 @@ Operation steps: Add documents from File Management -Files that have already been uploaded to **File** can be added to a knowledge base by connecting them to the target knowledge base. -Once connected, the files will be processed according to the configuration of the target knowledge base. -For detailed instructions, see [**File > Connect to a knowledge base**](../file/link_dataset.md) +Files that have already been uploaded to **File** can be added to a knowledge base by connecting them to the target knowledge base. Once connected, the files will be processed according to the configuration of the target knowledge base. For detailed instructions, see [**File > Connect to a knowledge base**](../file/link_dataset.md). ## Parse Documents diff --git a/docs/guides/dataset/notes_and_faqs.md b/docs/guides/dataset/notes_and_faqs.md index f09fcb457c..ac0e2e82a9 100644 --- a/docs/guides/dataset/notes_and_faqs.md +++ b/docs/guides/dataset/notes_and_faqs.md @@ -66,7 +66,7 @@ During retrieval testing, hybrid search is used to retrieve chunks created by th #### Similarity Threshold -This setting is the threshold for retrieving chunks. Chunks with similarity below the threshold are filtered out. By default, the threshold is set to `0.2`. This means only chunks with a hybrid similarity score of 20 or higher are retrieved. +This setting is the threshold for retrieving chunks. Chunks with similarity below the threshold are filtered out. By default, the threshold is set to `0.2`. This means only chunks with a hybrid similarity score of `0.2` or higher are retrieved. #### Vector Similarity Weight @@ -134,4 +134,4 @@ Please note that some of your settings may consume a large amount of time. If yo - On the dataset configuration page, turn off **Use RAPTOR to enhance retrieval**. - Extracting the knowledge graph (GraphRAG) is time-consuming. - On the dataset configuration page, disable **Auto keyword** and **Auto question**, because both depend on the LLM. -- v0.17.0+: If all PDFs in your dataset are pure text and do not require GPU-intensive processing such as OCR (optical character recognition), TSR (table structure recognition), or DLA (document layout analysis), select **Naive** instead of **DeepDoc** or other time-consuming large model options in the **Document parser** drop-down menu. This significantly reduces document parsing time. +- v0.17.0+: If all PDFs in your dataset are pure text and do not require compute-intensive processing such as OCR (optical character recognition), TSR (table structure recognition), or DLA (document layout analysis), select **Naive** instead of **DeepDoc** or other time-consuming large model options in the **Document parser** drop-down menu. This significantly reduces document parsing time. In the RAGFlow open-source 1.0 release, DeepDoc performs these operations with CPU inference. diff --git a/docs/guides/knowledge_compilation/runtime_configuration.md b/docs/guides/knowledge_compilation/runtime_configuration.md deleted file mode 100644 index 1223f85008..0000000000 --- a/docs/guides/knowledge_compilation/runtime_configuration.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -sidebar_position: 6 -title: Knowledge Compilation Runtime Configuration -sidebar_label: Runtime Configuration -slug: /knowledge_compilation/runtime_configuration -sidebar_custom_props: { - categoryIcon: LucideWandSparkles -} ---- - -# Knowledge Compilation Runtime Configuration - -Knowledge compilation runtime parameters can be configured with environment -variables. In the Docker deployment, set them in `docker/.env` and restart the -RAGFlow service for the changes to take effect. - -The values below are the defaults. If an environment variable is not set, its -default value is used. Invalid values are replaced with the default value. -Values below a configured minimum or above a configured maximum are clamped to -the valid range and logged. - -## Wiki Configuration - -| Environment variable | Default | Description | -| --- | ---: | --- | -| `WIKI_MAP_LLM_POOL_SIZE` | `20` | Maximum number of concurrent LLM calls allowed by the Wiki task's shared LLM pool. | -| `WIKI_MAP_MAX_PENDING` | `25` | Maximum number of active and waiting calls admitted by the Wiki LLM pool. The effective value is never lower than `WIKI_MAP_LLM_POOL_SIZE`. | -| `WIKI_REFINE_WORKERS` | `4` | Number of page-refinement workers. Actual LLM concurrency is still limited by the shared pool. | -| `WIKI_MAP_WORKERS` | `20` | Default worker count used by direct Wiki MAP calls. | -| `WIKI_MAP_TIMEOUT` | `600` seconds | Timeout for one Wiki MAP extraction call. | -| `WIKI_PLAN_TIMEOUT` | `600` seconds | Timeout for Wiki PLAN calls, including page planning and MAYBE resolution. | -| `WIKI_REFINE_TIMEOUT` | `300` seconds | Timeout for one Wiki page-writing call. | -| `WIKI_MERGE_TIMEOUT` | `600` seconds | Timeout for merging an existing Wiki page with newly generated content. | - -`WIKI_MAP_LLM_POOL_SIZE` is a hard ceiling for the task. The pool can reduce -the effective concurrency for a model after rate limiting, so setting this -value does not force every provider to receive that many concurrent requests. - -## Structure Compile Configuration - -| Environment variable | Default | Description | -| --- | ---: | --- | -| `DOC_STRUCTURE_LLM_POOL_SIZE` | `20` | Maximum number of concurrent LLM calls for a document Structure Compile task. | -| `DOC_STRUCTURE_COMPILE_MAX_IN_FLIGHT` | `15` | Maximum number of structure batch/template operations in flight. | -| `DOC_STRUCTURE_COMPILE_BATCH_CHUNKS` | `4` | Number of source chunks passed to one outer Structure Compile batch. | -| `STRUCTURE_CONTEXT_FRACTION` | `0.5` | Fraction of the model context window used when packing structure batches, clamped to `(0, 1]`. | -| `STRUCTURE_DEFAULT_CONTEXT` | `100000` tokens | Fallback model context size when the model does not provide one. | -| `KNOWLEDGE_GRAPH_CONTEXT_FRACTION` | `0.1` | Fraction of the model context window used for Knowledge Graph batches, clamped to `(0, 1]`. | -| `KNOWLEDGE_GRAPH_MIN_BATCH_TOKENS` | `2048` tokens | Minimum Knowledge Graph batch size. | -| `KNOWLEDGE_GRAPH_MAX_BATCH_TOKENS` | `4096` tokens | Maximum Knowledge Graph batch size. The effective value is never lower than `KNOWLEDGE_GRAPH_MIN_BATCH_TOKENS`. | -| `STRUCTURE_CHAIN_CORRECTION_TIMEOUT_S` | `120` seconds | Time limit for the Structure Compile chain-correction LLM step. | - -The regular Structure Compile entity/relation extraction path does not define -an independent application-level timeout. Its request timeout is determined by -the configured LLM provider/client. - -## LLM Pool Rate-Limit Handling - -These variables apply to the shared adaptive LLM pool: - -| Environment variable | Default | Description | -| --- | ---: | --- | -| `LLM_POOL_RATE_LIMIT_RETRIES` | `3` | Number of retries after a rate-limit response. | -| `LLM_POOL_RATE_LIMIT_RETRY_BASE_DELAY` | `1.0` second | Initial delay used by exponential backoff. | -| `LLM_POOL_RATE_LIMIT_RETRY_MAX_DELAY` | `30.0` seconds | Maximum delay between rate-limit retries. | - -After a rate-limit response, the pool lowers the effective concurrency for the -affected model and retries the request. Successful calls gradually restore -the model's concurrency up to the configured pool limit. - -The pool normalizes `max_pending` to at least the configured pool size, and -normalizes the retry maximum delay to at least the retry base delay. - -When all retries are exhausted, the backend records the detailed failure in -its service log and the frontend task log receives only the stage, context, and -error type. Provider response bodies are not forwarded to the frontend. - -## Example - -The following configuration lowers concurrency for providers with a smaller -request limit and shortens the Wiki MAP timeout: - -```dotenv -WIKI_MAP_LLM_POOL_SIZE=8 -WIKI_MAP_MAX_PENDING=10 -DOC_STRUCTURE_LLM_POOL_SIZE=8 -LLM_POOL_RATE_LIMIT_RETRIES=5 -WIKI_MAP_TIMEOUT=300 -``` - -Restart the RAGFlow backend after changing `docker/.env`. The settings are -read when the Python modules are loaded and are not changed for already-running -tasks. diff --git a/docs/guides/memory/configure_memory.md b/docs/guides/memory/configure_memory.md index 50953c42de..65cda71497 100644 --- a/docs/guides/memory/configure_memory.md +++ b/docs/guides/memory/configure_memory.md @@ -31,7 +31,7 @@ Multiple memory types can be selected, but **Raw (`raw`)** is required and canno ### Memory Size -Memory size is used to limit the capacity that the memory can occupy. The value range is `(0, 5242880]` bytes. After the capacity reaches the upper limit, the system cleans up old content according to the forgetting policy. +Memory size is used to limit the capacity that the memory can occupy. The value must be greater than `0` and cannot exceed `5 MiB` (`5242880` bytes). After the capacity reaches the upper limit, the system cleans up old content according to the forgetting policy. ### Advanced Settings diff --git a/docs/guides/models/deploy_local_llm.mdx b/docs/guides/models/deploy_local_llm.mdx index 8e1995c885..fef39d65de 100644 --- a/docs/guides/models/deploy_local_llm.mdx +++ b/docs/guides/models/deploy_local_llm.mdx @@ -343,9 +343,13 @@ Go to **Settings** → **Model Providers** → **Search** → **vLLM** → **Add ![add vllm](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/ragflow_vllm.png) Select the vLLM chat model as the default LLM model: + ![chat](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/ragflow_vllm1.png) + ### 5.3 Chat with vLLM Chat Model + Create a chat and start a conversation as follows: + ![chat](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/ragflow_vllm2.png) ### 6. Deploy GPUStack @@ -378,9 +382,9 @@ setting->model providers->search->gpustack->add ,configure as follow: ![add vllm](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/ragflow-gpustack11.png) -select gpustack chat model as default llm model as follow: +Select the GPUStack chat model as the default LLM: + ![chat](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/ragflow-gpustack22.png) - diff --git a/docs/guides/models/llm_api_key_setup.md b/docs/guides/models/llm_api_key_setup.md index 91c82dbdc9..4cf6db5e67 100644 --- a/docs/guides/models/llm_api_key_setup.md +++ b/docs/guides/models/llm_api_key_setup.md @@ -29,8 +29,7 @@ Go to **User settings** **>** **Model providers**. In **Available models**, sele ### Create a Model Provider Instance and Configure Connection Information -An instance stores a set of connection settings under a provider. You can create separate instances for test environments, production environments, local models, or proxy gateways to avoid mixing configurations for different purposes. -When you configure a provider for the first time, the right pane prompts you to create an instance first. After the instance is saved, you can continue to fill in **API Key** and **Base URL** and add models. +An instance stores a set of connection settings under a provider. You can create separate instances for test environments, production environments, local models, or proxy gateways to avoid mixing configurations for different purposes. When you configure a provider for the first time, the right pane prompts you to create an instance first. After the instance is saved, you can continue to fill in **API Key** and **Base URL** and add models. **API Key** is used for authentication. **Base URL** specifies the model service endpoint. diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index c2e3da2fb9..18e709b15f 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -5,248 +5,78 @@ sidebar_custom_props: { sidebarIcon: LucideRocket } --- -# Quickstart -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import APITable from '@site/src/components/APITable'; - RAGFlow is an open-source RAG (Retrieval-Augmented Generation) engine based on deep document understanding. When integrated with LLMs, it is capable of providing truthful question-answering capabilities, backed by well-founded citations from various complex formatted data. This quick start guide describes a general process from: - Starting up a local RAGFlow server, - Creating a dataset, -- Intervening with file parsing, to - Establishing an AI chat based on your datasets. :::danger IMPORTANT -We officially support x86 CPU and Nvidia GPU, and this document offers instructions on deploying RAGFlow using Docker on x86 platforms. While we also test RAGFlow on ARM64 platforms, we do not maintain RAGFlow Docker images for ARM. - -If you are on an ARM platform, follow [this guide](./develop/build_docker_image.mdx) to build a RAGFlow Docker image. +This guide deploys the Go backend with the repository's Go Docker image and Compose configuration. The supported native Docker build target is Linux x86-64. Linux ARM64 is not currently a supported native target because the Go image depends on native libraries published for x86-64. ::: ## Prerequisites -- CPU ≥ 4 cores (x86); -- RAM ≥ 16 GB; -- Disk ≥ 50 GB; -- Docker ≥ 24.0.0 & Docker Compose ≥ v2.26.1; -- Python ≥ 3.13; -- [gVisor](https://gvisor.dev/docs/user_guide/install/): Required only if you intend to use the code executor ([sandbox](https://github.com/infiniflow/ragflow/tree/main/agent/sandbox)) feature of RAGFlow. +- A recommended starting configuration of 4 CPU cores (x86-64), 16 GB RAM, and 50 GB free disk space. Actual requirements depend on the document engine, data volume, parsing workload, and concurrency. Local models and OceanBase require additional resources. +- Docker ≥ 24.0.0 with Docker Compose ≥ v2.26.1 and BuildKit; +- Access to the dependency image `infiniflow/ragflow_deps:latest` during the image build, and to an LLM and embedding model at runtime. -:::tip NOTE -If you have not installed Docker on your local machine (Windows, Mac, or Linux), see [Install Docker Engine](https://docs.docker.com/engine/install/). -::: +If Docker is not installed, see [Install Docker Engine](https://docs.docker.com/engine/install/). ## Start up the server -This section provides instructions on setting up the RAGFlow server on Linux. If you are on a different operating system, no worries. Most steps are alike. - -1. Ensure `vm.max_map_count` ≥ 262144. - -
- Expand to show details: - - `vm.max_map_count`. This value sets the maximum number of memory map areas a process may have. Its default value is 65530. While most applications require fewer than a thousand maps, reducing this value can result in abnormal behaviors, and the system will throw out-of-memory errors when a process reaches the limitation. - - RAGFlow v0.27.2 uses Elasticsearch or [Infinity](https://github.com/infiniflow/infinity) for multiple recall. Setting the value of `vm.max_map_count` correctly is crucial to the proper functioning of the Elasticsearch component. - - - - 1.1. Check the value of `vm.max_map_count`: +1. For the default Elasticsearch document engine, ensure `vm.max_map_count` is at least 262144 on the Docker host: ```bash - $ sysctl vm.max_map_count + sysctl vm.max_map_count + sudo sysctl -w vm.max_map_count=262144 ``` - 1.2. Reset `vm.max_map_count` to a value at least 262144 if it is not. + The change made with `sysctl -w` is temporary. To keep it after a reboot, set `vm.max_map_count=262144` in `/etc/sysctl.conf`. On Docker Desktop, apply the setting to its Linux VM. + +2. Clone the repository and build the Go image from its root: ```bash - $ sudo sysctl -w vm.max_map_count=262144 + git clone https://github.com/infiniflow/ragflow.git + cd ragflow + docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . ``` - :::caution WARNING - This change will be reset after a system reboot. If you forget to update the value the next time you start up the server, you may get a `Can't connect to ES cluster` exception. +3. Set `RAGFLOW_IMAGE=ragflow:go-local` in `docker/.env`. The same file controls `DOC_ENGINE`, service ports, and dependency credentials. Change the default passwords before deploying to a network-accessible host. + +4. Start the Go service and its dependencies: + + ```bash + cd docker + docker compose --env-file .env -f docker-compose.yml up -d + ``` + + In the RAGFlow open-source 1.0 release, DeepDoc layout analysis, OCR, and table recognition use CPU inference. + + :::caution Development checkouts + A development checkout can report a code version older than the database migration version, including immediately after its own migrations. In that case, the Go server refuses to start with `Refusing to start: database was migrated by a newer version`. For local development with this checkout, set `RAGFLOW_DEV_MODE=true` in `.env` and run the Compose command again. This disables the database downgrade check; leave `RAGFLOW_DEV_MODE=false` for production, and use a binary whose version is at least the database migration version. ::: - 1.3. To ensure your change remains permanent, add or update the `vm.max_map_count` value in **/etc/sysctl.conf** accordingly: +5. Check that the service is running: ```bash - vm.max_map_count=262144 + docker compose --env-file .env -f docker-compose.yml ps + docker compose --env-file .env -f docker-compose.yml logs -f ragflow-cpu ``` - - - If you are on macOS with Docker Desktop, run the following command to update `vm.max_map_count`: + + After initialization, check the Go API and its dependencies through the web port from another terminal: ```bash - docker run --rm --privileged --pid=host alpine sysctl -w vm.max_map_count=262144 + curl -f http://localhost/api/v1/system/healthz ``` - :::caution WARNING - This change will be reset after a system reboot. If you forget to update the value the next time you start up the server, you may get a `Can't connect to ES cluster` exception. - ::: + A successful response has HTTP status 200. If you changed `SVR_WEB_HTTP_PORT` in `.env`, include that port in the URL. Wait for this check to pass before opening the web interface. - To make your change persistent, create a file with proper settings: +6. Open `http://IP_OF_YOUR_MACHINE` in a browser and log in. If you changed `SVR_WEB_HTTP_PORT` in `.env`, include that port in the URL. - 1.1. Create a file: - - ```shell - sudo nano /Library/LaunchDaemons/com.user.vmmaxmap.plist - ``` - - 1.2. Open the file: - - ```shell - sudo launchctl load /Library/LaunchDaemons/com.user.vmmaxmap.plist - ``` - - 1.3. Add settings: - - ```xml - - - - - Label - com.user.vmmaxmap - ProgramArguments - - /usr/sbin/sysctl - -w - vm.max_map_count=262144 - - RunAtLoad - - - - ``` - - 1.4. After saving the file, load the new daemon: - - ```shell - sudo launchctl load /Library/LaunchDaemons/com.user.vmmaxmap.plist - ``` - - :::note - If the above steps do not work, consider using [this workaround](https://github.com/docker/for-mac/issues/7047#issuecomment-1791912053), which employs a container and does not require manual editing of the macOS settings. - ::: - - - - - #### If you are on Windows with Docker Desktop, then you *must* use docker-machine to set `vm.max_map_count`: - - ```bash - $ docker-machine ssh - $ sudo sysctl -w vm.max_map_count=262144 - ``` - #### If you are on Windows with Docker Desktop WSL 2 backend, then use docker-desktop to set `vm.max_map_count`: - - 1.1. Run the following in WSL: - ```bash - $ wsl -d docker-desktop -u root - $ sysctl -w vm.max_map_count=262144 - ``` - - :::caution WARNING - This change will be reset after you restart Docker. If you forget to update the value the next time you start up the server, you may get a `Can't connect to ES cluster` exception. - ::: - - 1.2. If you prefer not to run those commands every time you restart Docker, you can update your `%USERPROFILE%.wslconfig` as follows to keep your change permanent and global for all WSL distributions: - - ```bash - [wsl2] - kernelCommandLine = "sysctl.vm.max_map_count=262144" - ``` - *This causes all WSL2 virtual machines to have that setting assigned when they start.* - - :::note - If you are on Windows 11 or Windows 10 version 22H2, and have installed the Microsoft Store version of WSL, you can also update the **/etc/sysctl.conf** within the docker-desktop WSL distribution to keep your change permanent: - - ```bash - $ wsl -d docker-desktop -u root - $ vi /etc/sysctl.conf - ``` - - ```bash - # Append a line, which reads: - vm.max_map_count = 262144 - ``` - ::: - - - -
- -2. Clone the repo: - - ```bash - $ git clone https://github.com/infiniflow/ragflow.git - $ cd ragflow/docker - ``` - -3. Switch to the current version: - - ```bash - $ git checkout -f v0.27.2 - ``` -4. Use the pre-built Docker images and start up the server: - - ```bash - # Use CPU for DeepDoc tasks: - $ docker compose -f docker-compose.yml up -d - ``` - - ```mdx-code-block - - ``` - - | RAGFlow image tag | Image size (GB) | Stable? | - | ------------------- | --------------- | ------------------------ | - | v0.27.2 | ≈2 | Stable release | - | nightly | ≈2 | _Unstable_ nightly build | - - ```mdx-code-block - - ``` - - :::tip NOTE - The image size shown refers to the size of the *downloaded* Docker image, which is compressed. When Docker runs the image, it unpacks it, resulting in significantly greater disk usage. A Docker image will expand to around 7 GB once unpacked. - ::: - -5. Check the server status after having the server up and running: - - ```bash - $ docker logs -f docker-ragflow-cpu-1 - ``` - - _The following output confirms a successful launch of the system:_ - - ```bash - ____ ___ ______ ______ __ - / __ \ / | / ____// ____// /____ _ __ - / /_/ // /| | / / __ / /_ / // __ \| | /| / / - / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / - /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ - - * Running on all addresses (0.0.0.0) - ``` - - :::danger IMPORTANT - If you skip this confirmation step and directly log in to RAGFlow, your browser may prompt a `network anomaly` error because, at that moment, your RAGFlow may not be fully initialized. - ::: - -6. In your web browser, enter the IP address of your server and log in to RAGFlow. - - :::caution WARNING - With the default settings, you only need to enter `http://IP_OF_YOUR_MACHINE` (**sans** port number) as the default HTTP serving port `80` can be omitted when using the default configurations. - ::: +The Go container runs the API server, ingestion workers, and data synchronization. Its startup script runs the Go database migrations before starting the services. ## Configure LLMs @@ -262,7 +92,7 @@ To add and configure an LLM: 2. Click on the desired LLM and update the API key accordingly. -3. Click **System Model Settings** to select the default models: +3. Click **Set default models** to select the default models: - Chat model, - Embedding model, @@ -273,7 +103,7 @@ To add and configure an LLM: ## Create your first dataset -You are allowed to upload files to a dataset in RAGFlow and parse them into datasets. A dataset is virtually a collection of datasets. Question answering in RAGFlow can be based on a particular dataset or multiple datasets. File formats that RAGFlow supports include documents (PDF, DOC, DOCX, TXT, MD, MDX), tables (CSV, XLSX, XLS), pictures (JPEG, JPG, PNG, TIF, GIF), and slides (PPT, PPTX). +You can upload files to a dataset in RAGFlow and parse them into chunks. A dataset is a collection of documents. Question answering in RAGFlow can be based on one or more datasets. Supported file formats include documents (PDF, DOC, DOCX, TXT, MD, MDX), tables (CSV, XLSX, XLS), images (JPEG, JPG, PNG, TIF, GIF), and slides (PPT, PPTX). To create your first dataset: @@ -299,10 +129,7 @@ To create your first dataset: ![parse file](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/parse_file.jpg) - :::caution NOTE - - If your file parsing gets stuck at below 1%, see [this FAQ](./faq.mdx#why-does-my-document-parsing-stall-at-under-one-percent). - - If your file parsing gets stuck at near completion, see [this FAQ](./faq.mdx#why-does-my-pdf-parsing-stall-near-completion-while-the-log-does-not-show-any-error) - ::: + If parsing stalls, check the `ragflow-cpu` service logs with the Compose command above for ingestion errors. ## Intervene with file parsing @@ -336,28 +163,27 @@ Conversations in RAGFlow are based on a particular dataset or multiple datasets. 1. Click the **Chat** tab in the middle top of the page **>** **Create chat** to create a chat assistant. 2. Click the created chat app to enter its configuration page. - > RAGFlow offer the flexibility of choosing a different chat model for each dialogue, while allowing you to set the default models in **System Model Settings**. + > RAGFlow lets you choose a chat model for each dialogue. You can configure the defaults under **Set default models**. -2. Update **Chat setting** on the right of the configuration page: +3. Update **Chat setting** on the right of the configuration page: - Name your assistant and specify your datasets. - **Empty response**: - If you wish to *confine* RAGFlow's answers to your datasets, leave a response here. Then when it doesn't retrieve an answer, it *uniformly* responds with what you set here. - If you wish RAGFlow to *improvise* when it doesn't retrieve an answer from your datasets, leave it blank, which may give rise to hallucinations. -3. Update **System prompt** or leave it as is for the beginning. +4. Update **System prompt** or leave it as is for the beginning. -4. Select a chat model in the **Model** dropdown list. +5. Select a chat model in the **Model** dropdown list. -5. Now, let's start the show: +6. Now, let's start the show: ![chat_thermal_solution](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/chat_thermal_solution.jpg) :::tip NOTE -RAGFlow also offers HTTP and Python APIs for you to integrate RAGFlow's capabilities into your applications. Read the following documents for more information: +RAGFlow also offers an HTTP API for integrating its capabilities into your applications: - [Acquire a RAGFlow API key](./develop/acquire_ragflow_api_key.md) - [HTTP API reference](./references/http_api_reference.md) -- [Python API reference](./references/python_api_reference.md) ::: diff --git a/docs/references/http_api_reference.md b/docs/references/http_api_reference.md index 2affbe372e..5a5dd374bc 100644 --- a/docs/references/http_api_reference.md +++ b/docs/references/http_api_reference.md @@ -276,8 +276,7 @@ This API follows the same request and response format as OpenAI's API. It allows - `'Authorization: Bearer '` - Body: - `"agent_id"`: `string` - - `"openai-compatible"`: `boolean` (must be `true`) - - `"model"`: `string` + - `"openai-compatible"`: `boolean` - `"messages"`: `object list` - `"stream"`: `boolean` - `"session_id"`: `string` (optional) @@ -290,9 +289,8 @@ curl --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ - "agent_id": "AGENT_ID", + "agent_id": "{agent_id}", "openai-compatible": true, - "model": "model", "messages": [{"role": "user", "content": "Say this is a test!"}], "stream": true }' @@ -301,13 +299,10 @@ curl --request POST \ ##### Request Parameters - `agent_id` (*Body parameter*) `string`, *Required* - The ID of the associated agent. + The ID of the agent to run. - `openai-compatible` (*Body parameter*) `boolean`, *Required* - Must be `true` to enable the OpenAI-compatible response format. - -- `model` (*Body parameter*) `string` - The model used to generate the response. The server will parse this automatically, so you can set it to any value for now. + Set this field to `true` to use the OpenAI-compatible request and response format. - `messages` (*Body parameter*) `list[object]`, *Required* A list of historical chat messages used to generate the response. This must contain at least one message with the `user` role. @@ -598,14 +593,10 @@ curl --request POST \ - Maximum 65535 characters - `"language"`: (*Body parameter*), `string` - Optional document/dataset language, for example: `"English"` or `"Chinese"`. - Leading and trailing whitespace are stripped. - After trimming, it must contain at least 1 character and at most 32 characters. The limit counts characters, not UTF-8 bytes. - No restricted list of language values is enforced. - If omitted, the server/database default is used. + Optional document/dataset language, for example: `"English"` or `"Chinese"`. Leading and trailing whitespace are stripped. After trimming, it must contain at least 1 character and at most 32 characters. The limit counts characters, not UTF-8 bytes. No restricted list of language values is enforced. If omitted, the server/database default is used. - `"embedding_model"`: (*Body parameter*), `string` - The name of the embedding model to use. For example: `"BAAI/bge-large-zh-v1.5@BAAI"` + The name of the embedding model to use. For example: `"BAAI/bge-large-zh-v1.5@BAAI"`. - Maximum 255 characters - Must follow `model_name@model_factory` format @@ -779,7 +770,7 @@ curl --request DELETE \ - If omitted, or set to `null` or an empty array, no datasets are deleted. - If an array of IDs is provided, only the datasets matching those IDs are deleted. - `"delete_all"`: (*Body parameter*), `boolean` - Whether to delete all datasets owned by the current user when`"ids"` is omitted, or set to `null` or an empty array. Defaults to `false`. + Whether to delete all datasets owned by the current user when `"ids"` is omitted, or set to `null` or an empty array. Defaults to `false`. #### Response @@ -858,17 +849,13 @@ curl --request PUT \ - Maximum 255 characters - Must follow `model_name@model_factory` format - `"language"`: (*Body parameter*), `string` - Optional document/dataset language, for example: `"English"` or `"Chinese"`. - Leading and trailing whitespace are stripped. - After trimming, it must contain at least 1 character and at most 32 characters. The limit counts characters, not UTF-8 bytes. - No restricted list of language values is enforced. - If omitted, the existing dataset language remains unchanged. + Optional document/dataset language, for example: `"English"` or `"Chinese"`. Leading and trailing whitespace are stripped. After trimming, it must contain at least 1 character and at most 32 characters. The limit counts characters, not UTF-8 bytes. No restricted list of language values is enforced. If omitted, the existing dataset language remains unchanged. - `"permission"`: (*Body parameter*), `string` The updated dataset permission. Available options: - `"me"`: (Default) Only you can manage the dataset. - `"team"`: All team members can manage the dataset. - `"pagerank"`: (*Body parameter*), `int` - refer to [Set page rank](https://ragflow.io/docs/dev/set_page_rank) + Refer to [Set page rank](https://ragflow.io/docs/dev/set_page_rank). - Default: `0` - Minimum: `0` - Maximum: `100` @@ -907,7 +894,7 @@ curl --request PUT \ - Defaults to `false` - `"layout_recognize"`: `string` - Defaults to `DeepDOC` - - `"tag_kb_ids"`: `array` refer to [Use tag set](https://ragflow.io/docs/dev/use_tag_sets) + - `"tag_kb_ids"`: `array`. Refer to [Use tag set](https://ragflow.io/docs/dev/use_tag_sets). - Must include a list of dataset IDs, where each dataset is parsed using the ​​Tag Chunking Method - `"task_page_size"`: `int` For PDF only. - Defaults to `12` @@ -1482,7 +1469,7 @@ curl --request GET \ ```bash curl -G \ - --url "http://localhost:9222/api/v1/datasets/{{KB_ID}}/documents" \ + --url "http://{address}/api/v1/datasets/{dataset_id}/documents" \ --header 'Authorization: Bearer ' \ --data-urlencode 'metadata_condition={"logic":"and","conditions":[{"name":"tags","comparison_operator":"is","value":"bar"},{"name":"author","comparison_operator":"is","value":"alice"}]}' ``` @@ -2718,7 +2705,6 @@ curl --request POST \ - `"quote"`: `boolean` Whether the source of text should be displayed. Defaults to `true`. - `"tts"`: `boolean` - `"refine_multiturn"`: `boolean` - - `"use_kg"`: `boolean` - `"reasoning"`: `boolean` - `"cross_languages"`: `list[string]` - `"web_search_provider"`: `string` The web search service to use. Supported values are `"tavily"`, `"querit"`, `"serply"`, and `"youcom"`. If omitted, Tavily is selected only when `"tavily_api_key"` is configured; otherwise web search is disabled. @@ -3123,10 +3109,6 @@ Failure: Deletes chat assistants by ID. -:::caution DEPRECATED -The `chat_id` in the request body is deprecated, please use `ids` list. -::: - #### Request - Method: DELETE @@ -4116,10 +4098,6 @@ Failure: ### Create session with agent -:::danger DEPRECATED -This method is deprecated and no longer recommended. Use `Converse with agent` (`POST /api/v1/agents/chat/completions`) instead; it automatically creates a session ID for the associated agent when `session_id` is not specified. -::: - **POST** `/api/v1/agents/{agent_id}/sessions` Creates a session with an agent. @@ -4497,15 +4475,15 @@ curl --request POST \ The ID of the session. If it is not provided, a new session will be generated. - `"inputs"`: (*Body parameter*), `object` Values for variables defined in the **Begin** component. Each variable value must be an object containing a `"value"` field and may include a `"type"` field. +- `"files"`: (*Body parameter*), `array` + File descriptors returned by the Agent file upload endpoint. RAGFlow makes the uploaded files available to the Agent through `sys.files`. - `"user_id"`: (*Body parameter*), `string` The optional user-defined ID. Valid *only* when no `session_id` is provided. - `"chat_template_kwargs"`: (*Body parameter*), `object` Optional passthrough parameters for the underlying LLM's chat template. Commonly used to toggle thinking/reasoning modes on supported models (e.g., `{"enable_thinking": false}`). :::tip NOTE -For now, this method does *not* support a file type input/variable. As a workaround, use the following to upload a file to an agent: -`http://{address}/v1/canvas/upload/{agent_id}` -*You will get a corresponding file ID from its response body.* +Before sending a file in a conversation, upload it as multipart form data with the field name `file` to `POST http://{address}/api/v1/agents/{agent_id}/upload`. The endpoint accepts one or more files and returns a file descriptor for one file or an array of descriptors for multiple files. Pass the returned descriptor or descriptors in the `files` array of the conversation request. ::: ##### Response @@ -5662,9 +5640,9 @@ curl --location --request PUT 'http://{address}/api/v1/memories/d6775d4eeada11f0 - `memory_size`: (*Body parameter*), `int`, *Optional* - Defaults to `5*1024*1024` Bytes. Accounts for each message's content + its embedding vector (≈ Content + Dimensions × 8 Bytes). Example: A 1 KB message with 1024-dim embedding uses ~9 KB. The 5 MB default limit holds ~500 such messages. + Defaults to `5 MiB` (`5242880` bytes). Accounts for each message's content + its embedding vector (≈ Content + Dimensions × 8 Bytes). Example: A 1 KiB message with a 1024-dimension embedding uses approximately 9 KiB. The 5 MiB default limit holds approximately 500 such messages. - - Maximum 10 * 1024 * 1024 Bytes + - Maximum `5 MiB` (`5242880` bytes) - `forgetting_policy`: (*Body parameter*), `enum`, *Optional* @@ -6535,7 +6513,7 @@ Failure **GET** `/api/v1/system/healthz` -Check the health status of RAGFlow's dependencies (database, Redis, document engine, object storage). +Check the health status of RAGFlow's dependencies: metadata database, Kvrocks cache, document engine, object storage, and NATS message queue. :::caution REMOVED ALIAS `GET /v1/system/healthz` is not available in 1.0. Use this endpoint instead. @@ -6577,6 +6555,7 @@ Content-Type: application/json "redis": "ok", "doc_engine": "ok", "storage": "ok", + "message_queue": "ok", "status": "ok" } ``` @@ -6592,6 +6571,7 @@ Content-Type: application/json "redis": "nok", "doc_engine": "ok", "storage": "ok", + "message_queue": "ok", "status": "nok", "_meta": { "redis": { @@ -6605,6 +6585,7 @@ Content-Type: application/json Explanation: - Each service is reported as "ok" or "nok". +- The `redis` field reports the Redis-compatible Kvrocks cache; `message_queue` reports the NATS connection. - The top-level `status` reflects overall health. - If any service is "nok", detailed error info appears in `_meta`. @@ -7402,8 +7383,7 @@ or **POST** `/api/v1/workspaces/{workspace_id}/commits` -Creates a new snapshot commit for the specified workspace. -This endpoint also supports: +Creates a new snapshot commit for the specified workspace. This endpoint also supports: - `/api/v1/datasets/{dataset_id}/commits` (resolves dataset to its workspace) #### Request @@ -7489,8 +7469,7 @@ Failure: **GET** `/api/v1/workspaces/{workspace_id}/commits` -Lists all commits for the specified folder with pagination. -Also available at: +Lists all commits for the specified folder with pagination. Also available at: - `/api/v1/datasets/{dataset_id}/commits` #### Request @@ -7556,8 +7535,7 @@ Success: **GET** `/api/v1/workspaces/{workspace_id}/commits/{commit_id}` -Retrieves the details of a specific commit, including its file changes. -Also available at: +Retrieves the details of a specific commit, including its file changes. Also available at: - `/api/v1/datasets/{dataset_id}/commits/{commit_id}` #### Request @@ -7626,8 +7604,7 @@ Failure: **GET** `/api/v1/workspaces/{workspace_id}/commits/{commit_id}/files` -Lists the file changes associated with a specific commit. -Also available at: +Lists the file changes associated with a specific commit. Also available at: - `/api/v1/datasets/{dataset_id}/commits/{commit_id}/files` #### Request @@ -7674,8 +7651,7 @@ Success: **GET** `/api/v1/workspaces/{workspace_id}/commits/diff?from={commit_id}&to={commit_id}` -Compares two commits and returns the differences. -Also available at: +Compares two commits and returns the differences. Also available at: - `/api/v1/datasets/{dataset_id}/commits/diff?from=...&to=...` #### Request @@ -7741,8 +7717,7 @@ Failure: **GET** `/api/v1/workspaces/{workspace_id}/changes` -Returns the uncommitted changes for the specified folder (similar to `git status`). -Also available at: +Returns the uncommitted changes for the specified folder (similar to `git status`). Also available at: - `/api/v1/datasets/{dataset_id}/changes` #### Request @@ -7793,8 +7768,7 @@ Success: **GET** `/api/v1/workspaces/{workspace_id}/commits/{commit_id}/tree` -Retrieves the full folder tree snapshot as it existed at a specific commit. -Also available at: +Retrieves the full folder tree snapshot as it existed at a specific commit. Also available at: - `/api/v1/datasets/{dataset_id}/commits/{commit_id}/tree` #### Request @@ -7860,8 +7834,7 @@ Success: **GET** `/api/v1/workspaces/{workspace_id}/commits/{commit_id}/files/{file_id}/content` -Retrieves the file content as it existed at a specific commit. -Also available at: +Retrieves the file content as it existed at a specific commit. Also available at: - `/api/v1/datasets/{dataset_id}/commits/{commit_id}/files/{file_id}/content` #### Request diff --git a/docs/references/python_api_reference.md b/docs/references/python_api_reference.md index d7da3bdfad..5cdda3e6d7 100644 --- a/docs/references/python_api_reference.md +++ b/docs/references/python_api_reference.md @@ -1136,9 +1136,7 @@ RAGFlow.retrieve( rerank_id: str | None = None, keyword: bool = False, cross_languages: list[str] | None = None, - metadata_condition: dict | None = None, - use_kg: bool = False, - toc_enhance: bool = False) + metadata_condition: dict | None = None) ``` Retrieves chunks from specified datasets. @@ -1196,14 +1194,6 @@ The languages that should be translated into, in order to achieve keywords retri filter condition for `meta_fields`. -##### use_kg: `bool` - -Whether to enable graph-assisted retrieval for multi-hop queries. Defaults to `False`. - -##### toc_enhance: `bool` - -Whether to use extracted table-of-contents information during retrieval. Defaults to `False`. - #### Returns - Success: A list of `Chunk` objects representing the document chunks. @@ -1656,102 +1646,6 @@ assistant.delete_sessions(delete_all=True) --- -### Converse with chat assistant - -```python -Session.ask(question: str = "", stream: bool = False, **kwargs) -> Optional[Message, iter[Message]] -``` - -Asks a specified chat assistant a question to start an AI-powered conversation. - -:::tip NOTE -In streaming mode, not all responses include a reference, as this depends on the system's judgment. -::: - -#### Parameters - -##### question: `string`, *Required* - -The question to start an AI-powered conversation. Default to `""` - -##### stream: `bool` - -Indicates whether to output responses in a streaming way: - -- `True`: Enable streaming (default). -- `False`: Disable streaming. - -##### **kwargs - -The parameters in prompt(system). - -#### Returns - -- A `Message` object containing the response to the question if `stream` is set to `False`. -- An iterator containing multiple `message` objects (`iter[Message]`) if `stream` is set to `True` - -The following shows the attributes of a `Message` object: - -##### id: `string` - -The auto-generated message ID. - -##### content: `string` - -The content of the message. Defaults to `"Hi! I am your assistant, can I help you?"`. - -##### reference: `list[Chunk]` - -A list of `Chunk` objects representing references to the message, each containing the following attributes: - -- `id` `string` - The chunk ID. -- `content` `string` - The content of the chunk. -- `img_id` `string` - The ID of the snapshot of the chunk. Applicable only when the source of the chunk is an image, PPT, PPTX, or PDF file. -- `document_id` `string` - The ID of the referenced document. -- `document_name` `string` - The name of the referenced document. -- `document_metadata` `dict` - Optional document metadata, returned only when `extra_body.reference_metadata.include` is `true`. -- `position` `list[str]` - The location information of the chunk within the referenced document. -- `dataset_id` `string` - The ID of the dataset to which the referenced document belongs. -- `similarity` `float` - A composite similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity. It is the weighted sum of `vector_similarity` and `term_similarity`. -- `vector_similarity` `float` - A vector similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity between vector embeddings. -- `term_similarity` `float` - A keyword similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity between keywords. - -#### Examples - -```python -from ragflow_sdk import RAGFlow - -rag_object = RAGFlow(api_key="", base_url="http://:9380") -assistant = rag_object.list_chats(name="Miss R") -assistant = assistant[0] -session = assistant.create_session() - -print("\n==================== Miss R =====================\n") -print("Hello. What can I do for you?") - -while True: - question = input("\n==================== User =====================\n> ") - print("\n==================== Miss R =====================\n") - - cont = "" - for ans in session.ask(question, stream=True): - print(ans.content[len(cont):], end='', flush=True) - cont = ans.content -``` - ---- - ### Create session with agent ```python @@ -2359,9 +2253,9 @@ Configurations to update. Available configurations: - `memory_size`: `int`, *Optional* - Defaults to `5*1024*1024` Bytes. Accounts for each message's content + its embedding vector (≈ Content + Dimensions × 8 Bytes). Example: A 1 KB message with 1024-dim embedding uses ~9 KB. The 5 MB default limit holds ~500 such messages. + Defaults to `5 MiB` (`5242880` bytes). Accounts for each message's content + its embedding vector (≈ Content + Dimensions × 8 Bytes). Example: A 1 KiB message with a 1024-dimension embedding uses approximately 9 KiB. The 5 MiB default limit holds approximately 500 such messages. - - Maximum 10 * 1024 * 1024 Bytes + - Maximum `5 MiB` (`5242880` bytes) - `forgetting_policy`: `enum`, *Optional* diff --git a/internal/cli/README.md b/internal/cli/README.md index 5442a8edf9..6a47fe7941 100644 --- a/internal/cli/README.md +++ b/internal/cli/README.md @@ -1,14 +1,13 @@ # RAGFlow CLI (Go Version) -This is the Go implementation of the RAGFlow command-line interface, compatible with the Python version's syntax. +This is the Go implementation of the RAGFlow command-line interface. ## Features - Interactive mode and single command execution -- Full compatibility with Python CLI syntax - Recursive descent parser for SQL-like commands - Virtual Filesystem for intuitive resource management -- Support for all major commands: +- Support for major commands, including: - User management: LOGIN, REGISTER, CREATE USER, DROP USER, LIST USERS, etc. - Service management: LIST SERVICES, SHOW SERVICE, STARTUP/SHUTDOWN/RESTART SERVICE - Role management: CREATE ROLE, DROP ROLE, LIST ROLES, GRANT/REVOKE PERMISSION @@ -16,15 +15,53 @@ This is the Go implementation of the RAGFlow command-line interface, compatible - Model management: SET/RESET DEFAULT LLM/VLM/EMBEDDING/etc. - And more... +## Installation + +For regular use, install a prebuilt Go binary from the latest RAGFlow GitHub Release. The installers detect the platform, download the matching binary, and verify its SHA-256 checksum. + +### Linux and macOS + +```bash +curl -fsSL https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.sh | sh +``` + +The default installation path is `/usr/local/bin/ragflow-cli`. To use another directory, set `INSTALL_DIR`: + +```bash +curl -fsSL https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.sh | INSTALL_DIR="$HOME/.local/bin" sh +``` + +### Windows PowerShell + +```powershell +irm https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.ps1 | iex +``` + +The Windows installer uses `%LOCALAPPDATA%\Programs\RAGFlow` by default and adds it to the user `PATH`. Restart the terminal after installation if prompted. + +Verify the installation: + +```bash +ragflow-cli --version +``` + ## Usage -### Build and run +### Build and run from source ```bash go build -o ragflow-cli ./cmd/ragflow-cli.go ./ragflow-cli ``` +### Interactive meta-commands + +The currently implemented meta-commands are: + +- `\?`, `\h`, or `\help`: show help. +- `\pwd`: show the current working directory. +- `\q`, `\quit`, or `\exit`: exit the CLI. + ## Architecture ``` @@ -39,7 +76,7 @@ internal/cli/ └── filesystem/ # Virtual Filesystem ├── engine.go # Core engine: path resolution, command routing ├── types.go # Node, Command, Result types - ├── base.go # Provider interface definition + ├── base.go # Provider interface definition ├── dataset.go # Dataset provider implementation ├── file.go # File manager provider implementation └── utils.go # Helper functions @@ -157,6 +194,7 @@ LIST DATASET 'my_dataset' SYNC_LOGS; SET DEFAULT LLM 'gpt-4'; SET DEFAULT EMBEDDING 'text-embedding-ada-002'; RESET DEFAULT LLM; +``` ## Parser Implementation @@ -166,4 +204,4 @@ The parser uses a hand-written recursive descent approach instead of go-yacc for - Easier to extend and maintain - No code generation step required -The parser structure follows the grammar defined in the Python version, ensuring full syntax compatibility. +The parser uses the SQL-like command grammar documented in this guide. diff --git a/tools/scripts/INSTALL_SCRIPTS_README.md b/tools/scripts/INSTALL_SCRIPTS_README.md index da76afd5c2..04bec6a9da 100644 --- a/tools/scripts/INSTALL_SCRIPTS_README.md +++ b/tools/scripts/INSTALL_SCRIPTS_README.md @@ -10,22 +10,22 @@ The release workflow builds the binaries with `CGO_ENABLED=0`, uploads `SHA256SU ## Linux And macOS -Use the hosted script: +Use the script maintained in the RAGFlow repository: ```sh -curl -sSfL https://your-domain/install.sh | sh +curl -fsSL https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.sh | sh ``` Install a specific version: ```sh -curl -sSfL https://your-domain/install.sh | VERSION=v1.0.0 sh +curl -fsSL https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.sh | VERSION=v1.0.0 sh ``` Install to a user-writable directory: ```sh -curl -sSfL https://your-domain/install.sh | INSTALL_DIR="$HOME/.local/bin" sh +curl -fsSL https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.sh | INSTALL_DIR="$HOME/.local/bin" sh ``` The Unix installer: @@ -38,11 +38,10 @@ The Unix installer: ## Windows PowerShell -Use the hosted script: +Run the repository script in PowerShell: ```powershell -iwr https://your-domain/install.ps1 -OutFile install.ps1 -powershell -ExecutionPolicy Bypass -File .\install.ps1 +irm https://raw.githubusercontent.com/infiniflow/ragflow/main/tools/scripts/install.ps1 | iex ``` Install a specific version: @@ -80,20 +79,5 @@ install.sh install.ps1 ``` -## Hosting Options - -Use a static domain for the public one-line command: - -```text -https://your-domain/install.sh -https://your-domain/install.ps1 -``` - -The same scripts can also be used directly from a GitHub Release asset, for example: - -```text -https://github.com/infiniflow/ragflow/releases/download/v1.0.0/install.sh -https://github.com/infiniflow/ragflow/releases/download/v1.0.0/install.ps1 -``` - -By default, both scripts install the latest stable GitHub Release. Set `VERSION` on Unix or `-Version` on Windows to pin a specific release. +By default, both scripts install the latest stable GitHub Release. Set +`VERSION` on Unix or `-Version` on Windows to pin a specific release.