From 3ce34f3040824269ea301a26e05063aeea2bd8f5 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sat, 17 Oct 2026 02:52:20 -0700 Subject: [PATCH 1/9] docs(integrations): RAGFlow tracing (TH-8233) New page /docs/integrations/no-code/ragflow for the per-tenant Future AGI exporter in the future-agi/ragflow fork (PR #1): build from the fork, save keys with /api/v1/futureagi/api-key, the chat/retrieval/LLM span tree, privacy default and redact, failure behaviour, how it differs from RAGFlow's Langfuse and OTEL_HOST settings, tested versions (fork at 2400ca8 / v1.0.0-rc1 tree and merged onto v1.0.0-rc2), limits and troubleshooting. No navigation change. Co-Authored-By: Claude Opus 5.5 --- .../docs/integrations/no-code/ragflow.mdx | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 src/pages/docs/integrations/no-code/ragflow.mdx diff --git a/src/pages/docs/integrations/no-code/ragflow.mdx b/src/pages/docs/integrations/no-code/ragflow.mdx new file mode 100644 index 000000000..a5cbb5922 --- /dev/null +++ b/src/pages/docs/integrations/no-code/ragflow.mdx @@ -0,0 +1,151 @@ +--- +title: "Send RAGFlow chats to Observe" +description: "Save Future AGI keys for a RAGFlow tenant on a RAGFlow build from the future-agi fork, and every chat turn becomes a trace in Observe: the turn, the retrieval with chunk ids and scores, and the answer call with model and tokens. Fork only until it is accepted upstream." +--- + +## About + +RAGFlow is an open-source RAG engine: chat assistants answer from knowledge bases (and optionally web search) with citations. RAGFlow already has a per-tenant Langfuse integration. The Future AGI exporter sits next to it: a tenant saves Future AGI keys once, and from then on every chat turn of that tenant's chat assistants lands in an Observe project as one trace. + +You configure RAGFlow only. Chat assistants do not change, and there is nothing to install in your application. + +| | | +| --- | --- | +| Tested with | The fork branch [`future-agi/ragflow` `feat/th-8233-futureagi-export`](https://github.com/future-agi/ragflow/pull/1), which is RAGFlow `main` at `2400ca8` (the `v1.0.0-rc1` Go tree) plus the exporter; and the same commits merged onto RAGFlow `v1.0.0-rc2` (released 2026-10-16, the newest release on GitHub; still a release candidate, there is no `v1.0.0` yet). Go 1.27. | +| Not supported | Stock RAGFlow images and releases (they do not contain the exporter), and the Python-era `v0.x` line (latest `v0.27.2`). | +| Future AGI side | A self-hosted Future AGI stack built from `dev` (collector on `/tracer/v1/traces`). | +| Models used | A real GPT model through RAGFlow's **OpenAI-API-Compatible** model provider. Web search through RAGFlow's Tavily provider. | + + +Alpha, fork only. What ran: RAGFlow's own services in process, with real model and Tavily calls, exporting to a real Future AGI collector: the model provider and chat assistant services, the chat session completion (`/api/v1/chat/completions`, the path the RAGFlow web chat uses; streamed, with web search), the OpenAI-compatible endpoint (`/api/v1/openai/{chat_id}/chat/completions`, not streamed), a chat whose model key is wrong, hidden content, wrong Future AGI keys and a collector that refuses connections, on both RAGFlow trees above. SQLite stood in for MySQL and no document engine was running. What did not run: the full RAGFlow Docker stack and its web UI (it needs more memory than our test machine had), knowledge-base retrieval against Elasticsearch or Infinity, the embedded chatbot endpoint (`/api/v1/chatbots/{id}/completions`), agentic reasoning mode, and the hosted Future AGI service. + + +## Where the exporter comes from + +The exporter is in the [future-agi/ragflow](https://github.com/future-agi/ragflow) fork, next to RAGFlow's Langfuse client in the Go API server: a `tenant_futureagi` table, a `/api/v1/futureagi/api-key` settings API shaped like `/api/v1/langfuse/api-key`, and a few hooks in the chat pipeline. It has not been submitted to `infiniflow/ragflow` yet. + +RAGFlow's own OpenTelemetry settings (the `otel` block, `OTEL_HOST` and `OTEL_PORT`) are not used. They have no field for headers, no exporter is wired to them in `v1.0.0-rc1` or `v1.0.0-rc2`, and the spans RAGFlow creates for its agent graph engine carry no model, prompt or token data. + +## Before you start + +- A Future AGI API key and secret key, and the name of the Observe project you want the traces in. The self-hosted stack we tested created the project on the first trace. If you are not sure your workspace does the same, create the project first. +- A RAGFlow server built from the fork, and a RAGFlow API key (or login token) of the account that owns the chat assistants. Keys are saved per tenant, the same as Langfuse keys: the account that owns a chat assistant decides where its chats are traced. + +## Build RAGFlow from the fork + +Build the image the way RAGFlow's [Build RAGFlow Docker image](https://github.com/infiniflow/ragflow/blob/main/docs/develop/build_docker_image.mdx) guide describes, from the fork branch: + +```bash +git clone --branch feat/th-8233-futureagi-export https://github.com/future-agi/ragflow.git +cd ragflow +docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . +# then set RAGFLOW_IMAGE=ragflow:go-local in docker/.env +cd docker && docker compose -f docker-compose.yml up -d +``` + +The container runs RAGFlow's database migration at start, which creates the `tenant_futureagi` table. We did not build or run this image ourselves; the runs above used the same Go code in process. + +## Configure + +Save the keys once per tenant with the settings API: + +```bash +curl -X POST "http:///api/v1/futureagi/api-key" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "api_key": "", + "secret_key": "", + "project_name": "my-ragflow-app", + "endpoint": "https://api.futureagi.com", + "redact": false + }' +``` + +| Field | Required | Meaning | +| --- | --- | --- | +| `api_key` | Yes | Future AGI API key. Sent as the `X-Api-Key` header. | +| `secret_key` | Yes | Future AGI secret key. Sent as the `X-Secret-Key` header. | +| `project_name` | Yes | The Observe project for every chat of this tenant. | +| `endpoint` | No | Default `https://api.futureagi.com`. For a self-hosted collector, for example `http://collector:4318`. RAGFlow appends `/tracer/v1/traces`. | +| `redact` | No | Default `false`. `true` hides content. See [Privacy](#privacy). | + +Before it stores anything, RAGFlow posts an empty trace export with the keys to the collector. Wrong keys fail the save with `invalid Future AGI keys`, an unreachable collector with `cannot verify the Future AGI keys: ...`, and the stored settings stay as they were. + +The same path also answers `PUT` (same body), `GET` (the stored settings, with both keys masked to their last four characters) and `DELETE` (stop exporting). Changes apply from the next chat turn; there is no restart. + +There is no settings dialog in the RAGFlow web UI yet; use the API. + +The exporter sends OTLP/HTTP JSON, uncompressed (the Future AGI collector does not accept gzip), with the resource attributes `project_name`, `project_type=observe` and `service.name=ragflow`. The trace is sent when the chat turn ends. + +## What you see in Observe + +One trace per chat turn, from every chat entry point: the RAGFlow web chat and `/api/v1/chat/completions`, the OpenAI-compatible endpoint `/api/v1/openai/{chat_id}/chat/completions`, and embedded chatbots `/api/v1/chatbots/{id}/completions` (the last one was not run). + +| Span | What it is | +| --- | --- | +| `ragflow.chat` (root, `chain`) | The turn. Input is the user's question, output the answer. ERROR when RAGFlow answered with an error. | +| `ragflow.retrieval` (`retriever`) | When the chat retrieved (knowledge bases and/or web search). Input is the search question. Each retrieved chunk is a `retrieval.documents.N.document.*` entry: chunk id, similarity score, chunk text, and metadata (document id, document name, knowledge base id, vector and term similarity, URL for web results). Also `ragflow.retrieval.chunk_count`, `top_n`, `top_k`, `similarity_threshold`, `vector_similarity_weight`, `ragflow.kb_count`, and the rerank model when one is set. | +| `ragflow.llm` (`llm`) | The answer call. `llm.model_name` / `gen_ai.request.model`, `gen_ai.provider.name` (the RAGFlow model provider), the input messages (system prompt with the retrieved knowledge, then the conversation), the answer, and prompt / completion / total tokens. | + +Root attributes: `session.id` and `gen_ai.conversation.id` (the RAGFlow conversation id; the chat assistant id on the OpenAI-compatible endpoint, which has no conversation), `user.id` and `ragflow.tenant_id` (the tenant id, not an end user), `ragflow.chat_id`, `ragflow.pipeline` (`rag`, `solo` for assistants without retrieval, `other`), `ragflow.stream`. + +Token counts are the ones RAGFlow computes itself with the `cl100k` tokenizer, the same numbers it reports to Langfuse (`ragflow.usage.source=ragflow_cl100k_count`). They can differ slightly from the provider's own count. + +Real example from the tested chat (web search on, streamed): three spans. `ragflow.chat` 6.2 s, `ragflow.retrieval` 2.3 s with six Tavily results (ids, scores 0.87 to 0.90, page text), `ragflow.llm` 3.8 s with `gpt-6-luna` and 1,844 / 82 tokens. The OpenAI-compatible call on an assistant without retrieval is two spans: `ragflow.chat` and `ragflow.llm` (39 / 38 tokens). + +Not captured: the steps inside agentic reasoning mode and SQL answers (only the `ragflow.chat` span), query refinement and keyword-extraction model calls, embedding and rerank calls (no separate spans), RAGFlow agent canvases, document ingestion, cost when the model is unknown to Future AGI, and a second Observe project for the same tenant. + +## Privacy + +Content is exported by default, like RAGFlow's Langfuse integration and the traceAI convention: questions, answers, the prompt sent to the model (including the retrieved knowledge), chunk text and document names. + +To hide content for a tenant, save the settings with `"redact": true`. With redact on, the export keeps the trace shape, span names, model, token counts, timings, status, chunk ids and similarity scores, and drops every question, answer, message, system prompt, chunk text and document name. Web-search chunk ids, which RAGFlow builds from the page URL, are replaced by a stable hash, and error text is replaced by a fixed line. + +This was checked, not assumed. A unique marker and an email address were put into the question of a web-search chat, a failing chat and an OpenAI-compatible call with redact on. Every stored column for those traces (ClickHouse `spans` including resource attributes, span events and the extra-attributes column, plus `traces`, `trace_sessions` and `end_users`) was searched: neither was found, nor the question text, the system prompt, a web result host or the model's error text. With the defaults, the marker, question and system prompt were found in the stored spans. + +In both modes: + +- Error text has URLs, IP addresses, email addresses, file paths, and the server's user and host names masked, and is capped at 512 characters. For example, a model call rejected with a wrong key is stored as `API request failed with status 401: {"error":"Invalid API key"}`, without the model host. +- The server's home directory is replaced with `~` in every exported value. +- The resource carries only `project_name`, `project_type` and `service.name`. No host name, user name or process path. A search of every stored column for the OS user name, host name, home directory, the model host and port, and all keys used found none of them. +- `user.id` is the RAGFlow tenant id and `session.id` the RAGFlow conversation or assistant id. Both are opaque ids and stay when redact is on. + +The Future AGI keys are stored as plain columns in `tenant_futureagi`, the same protection RAGFlow gives Langfuse keys today. `GET` returns them masked. + +## Errors and failure behaviour + +A failed turn is marked ERROR on `ragflow.chat`, and on `ragflow.llm` when the model call failed. The tested chat with a wrong model key gave two ERROR spans, both with `API request failed with status 401: {"error":"Invalid API key"}`. + +Tracing never changes the chat: + +- **Wrong keys at save time.** The save fails; nothing is stored. +- **Collector down later.** Chats answered normally and in their usual time (6 s for the web-search chat), the traces were dropped, and RAGFlow logged at most one warning a minute: `Future AGI: chat trace dropped; chats are not affected` with `reason: Future AGI collector unreachable`. +- **Busy collector.** Each tenant has one background exporter with a queue of 1,024 traces and a 5 s request timeout. A full queue drops the trace instead of waiting. +- **Shutdown.** When the API server stops, it waits up to 2 s for queued traces to be sent. A hard kill can lose the last traces. + +## How this differs from related integrations + +- **RAGFlow's Langfuse integration.** Both can be on at once; they are independent. The Langfuse client is only called from the OpenAI-compatible endpoint and records a generation whose output is RAGFlow's timing block; the Future AGI exporter covers every chat entry point, records the answer text and adds the retrieval span. Future AGI does not accept RAGFlow's Langfuse payloads. +- **RAGFlow's OpenTelemetry settings (`OTEL_HOST`).** Do not point them at Future AGI: they cannot send the API key headers or `project_name`, and nothing exports chat spans through them. +- **traceAI packages ([LangChain](/docs/integrations/traceai/langchain) and others).** Those instrument code you write yourself. RAGFlow is a server with its own Go pipeline, so use this exporter instead of a traceAI package. +- **Other no-code builders (Dify, Flowise, Langflow).** Each has its own integration; this page covers RAGFlow only. + +## Limits and what was not tested + +- Fork only. Stock RAGFlow images do not have the exporter. It is not in an upstream release. +- One Observe project per tenant. All chat assistants of a tenant share it. +- Not run: the full RAGFlow Docker stack and its web UI, knowledge-base retrieval against a real document engine (the retrieval span maps the same chunk fields RAGFlow's knowledge-base retrieval returns; that mapping is unit tested), the embedded chatbot endpoint, agentic reasoning mode, MySQL, and the hosted Future AGI service. +- No settings dialog in the RAGFlow web UI; configure with the API. +- Agent canvases (RAGFlow's agent builder) are not traced by this exporter. + +## Troubleshooting + +| What you see | What it means | +| --- | --- | +| `invalid Future AGI keys` when saving | The collector rejected the API key / secret key pair. Nothing was stored. | +| `cannot verify the Future AGI keys: Future AGI collector unreachable` | RAGFlow cannot reach `endpoint`. Check the URL; RAGFlow adds `/tracer/v1/traces` itself. | +| `Future AGI: chat trace dropped; chats are not affected` in the RAGFlow log | The collector stopped answering, or answered with an error (the `reason` field says which). Chats are unaffected. | +| No traces and no log line | No settings are saved for the tenant that owns the chat assistant (`GET /api/v1/futureagi/api-key` with that account), or this RAGFlow build does not have the exporter. | +| Traces have no inputs or outputs | `redact` is `true` for the tenant. | +| Agentic or SQL answers have only one span | Expected: those paths are traced as the `ragflow.chat` span only. | From 5c5ba4cd4cc8faeab30b2d60df8ac35e9f31ff31 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Tue, 20 Oct 2026 03:42:57 -0700 Subject: [PATCH 2/9] docs(integrations): RAGFlow settings dialog and verification section Co-Authored-By: Claude Sonnet 5.5 --- .../docs/integrations/no-code/ragflow.mdx | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/integrations/no-code/ragflow.mdx b/src/pages/docs/integrations/no-code/ragflow.mdx index a5cbb5922..fda0567d5 100644 --- a/src/pages/docs/integrations/no-code/ragflow.mdx +++ b/src/pages/docs/integrations/no-code/ragflow.mdx @@ -17,7 +17,7 @@ You configure RAGFlow only. Chat assistants do not change, and there is nothing | Models used | A real GPT model through RAGFlow's **OpenAI-API-Compatible** model provider. Web search through RAGFlow's Tavily provider. | -Alpha, fork only. What ran: RAGFlow's own services in process, with real model and Tavily calls, exporting to a real Future AGI collector: the model provider and chat assistant services, the chat session completion (`/api/v1/chat/completions`, the path the RAGFlow web chat uses; streamed, with web search), the OpenAI-compatible endpoint (`/api/v1/openai/{chat_id}/chat/completions`, not streamed), a chat whose model key is wrong, hidden content, wrong Future AGI keys and a collector that refuses connections, on both RAGFlow trees above. SQLite stood in for MySQL and no document engine was running. What did not run: the full RAGFlow Docker stack and its web UI (it needs more memory than our test machine had), knowledge-base retrieval against Elasticsearch or Infinity, the embedded chatbot endpoint (`/api/v1/chatbots/{id}/completions`), agentic reasoning mode, and the hosted Future AGI service. +Alpha, fork only. What ran: RAGFlow's own services in process, with real model and Tavily calls, exporting to a real Future AGI collector: the model provider and chat assistant services, the chat session completion (`/api/v1/chat/completions`, the path the RAGFlow web chat uses; streamed, with web search), the OpenAI-compatible endpoint (`/api/v1/openai/{chat_id}/chat/completions`, not streamed), a chat whose model key is wrong, hidden content, wrong Future AGI keys and a collector that refuses connections, on both RAGFlow trees above. SQLite stood in for MySQL and no document engine was running. What did not run: the full RAGFlow Docker stack and its web UI, including the settings dialog (it needs more memory than our test machine had), knowledge-base retrieval against Elasticsearch or Infinity, the embedded chatbot endpoint (`/api/v1/chatbots/{id}/completions`), agentic reasoning mode, and the hosted Future AGI service. ## Where the exporter comes from @@ -74,7 +74,7 @@ Before it stores anything, RAGFlow posts an empty trace export with the keys to The same path also answers `PUT` (same body), `GET` (the stored settings, with both keys masked to their last four characters) and `DELETE` (stop exporting). Changes apply from the next chat turn; there is no restart. -There is no settings dialog in the RAGFlow web UI yet; use the API. +You can also set it in the RAGFlow web UI, where the Langfuse settings are: avatar, **API**, scroll to the bottom, **Future AGI** card, **Configuration**. The dialog has the same fields. It never fills in the keys (the server only returns them masked), so enter both keys each time you save. The dialog was checked with RAGFlow's own formatter and linter only; it was not rendered in a browser. The exporter sends OTLP/HTTP JSON, uncompressed (the Future AGI collector does not accept gzip), with the resource attributes `project_name`, `project_type=observe` and `service.name=ragflow`. The trace is sent when the chat turn ends. @@ -136,9 +136,22 @@ Tracing never changes the chat: - Fork only. Stock RAGFlow images do not have the exporter. It is not in an upstream release. - One Observe project per tenant. All chat assistants of a tenant share it. - Not run: the full RAGFlow Docker stack and its web UI, knowledge-base retrieval against a real document engine (the retrieval span maps the same chunk fields RAGFlow's knowledge-base retrieval returns; that mapping is unit tested), the embedded chatbot endpoint, agentic reasoning mode, MySQL, and the hosted Future AGI service. -- No settings dialog in the RAGFlow web UI; configure with the API. +- The settings dialog is new and was not rendered; if it misbehaves, configure with the API. - Agent canvases (RAGFlow's agent builder) are not traced by this exporter. +## Verification (2026-10-20) + +What ran, on a Mac with Go 1.27 (darwin/arm64, `CGO_ENABLED=0`): + +- **RAGFlow's Go server path, in process.** RAGFlow's own services (model provider, chat assistant, chat session completion with web search, OpenAI-compatible endpoint) on SQLite, with a real model, real Tavily and a real Future AGI collector. Results and trace ids are in the [fork pull request](https://github.com/future-agi/ragflow/pull/1) (2026-10-17 runs, fork branch and merged onto `v1.0.0-rc2`). +- **Unit tests** for the exporter, the settings service and the settings handler, beside RAGFlow's existing Langfuse tests, and `go vet` and `gofmt` on the touched packages. +- **Formatter and linter** (`oxfmt`, `oxlint`, the versions RAGFlow's pre-commit uses) on the settings dialog files. + +What did not run: + +- The full RAGFlow Docker stack (about 16 GB of memory; the machine could not spare it) and the RAGFlow web UI, so the settings dialog was not opened and the TypeScript was not type-checked. +- Knowledge-base retrieval against Elasticsearch or Infinity, the embedded chatbot endpoint, agentic reasoning mode, MySQL, and the hosted Future AGI service. + ## Troubleshooting | What you see | What it means | From 67254754f78af42bac8e8d91e04546f6e84078b1 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 21 Oct 2026 15:42:11 -0700 Subject: [PATCH 3/9] docs(ragflow): settings card checks from the 2026-10-20 run The card was type-checked, linted and rendered headless with the settings API mocked; the page said it was never rendered or type-checked. Co-Authored-By: Claude Opus 5.5 --- src/pages/docs/integrations/no-code/ragflow.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pages/docs/integrations/no-code/ragflow.mdx b/src/pages/docs/integrations/no-code/ragflow.mdx index fda0567d5..1f6905d05 100644 --- a/src/pages/docs/integrations/no-code/ragflow.mdx +++ b/src/pages/docs/integrations/no-code/ragflow.mdx @@ -17,7 +17,7 @@ You configure RAGFlow only. Chat assistants do not change, and there is nothing | Models used | A real GPT model through RAGFlow's **OpenAI-API-Compatible** model provider. Web search through RAGFlow's Tavily provider. | -Alpha, fork only. What ran: RAGFlow's own services in process, with real model and Tavily calls, exporting to a real Future AGI collector: the model provider and chat assistant services, the chat session completion (`/api/v1/chat/completions`, the path the RAGFlow web chat uses; streamed, with web search), the OpenAI-compatible endpoint (`/api/v1/openai/{chat_id}/chat/completions`, not streamed), a chat whose model key is wrong, hidden content, wrong Future AGI keys and a collector that refuses connections, on both RAGFlow trees above. SQLite stood in for MySQL and no document engine was running. What did not run: the full RAGFlow Docker stack and its web UI, including the settings dialog (it needs more memory than our test machine had), knowledge-base retrieval against Elasticsearch or Infinity, the embedded chatbot endpoint (`/api/v1/chatbots/{id}/completions`), agentic reasoning mode, and the hosted Future AGI service. +Alpha, fork only. What ran: RAGFlow's own services in process, with real model and Tavily calls, exporting to a real Future AGI collector: the model provider and chat assistant services, the chat session completion (`/api/v1/chat/completions`, the path the RAGFlow web chat uses; streamed, with web search), the OpenAI-compatible endpoint (`/api/v1/openai/{chat_id}/chat/completions`, not streamed), a chat whose model key is wrong, hidden content, wrong Future AGI keys and a collector that refuses connections, on both RAGFlow trees above. SQLite stood in for MySQL and no document engine was running. What did not run: the full RAGFlow Docker stack and its web UI against a running server (it needs more memory than our test machine had; the settings card was rendered headless with the settings API mocked instead), knowledge-base retrieval against Elasticsearch or Infinity, the embedded chatbot endpoint (`/api/v1/chatbots/{id}/completions`), agentic reasoning mode, and the hosted Future AGI service. ## Where the exporter comes from @@ -74,7 +74,7 @@ Before it stores anything, RAGFlow posts an empty trace export with the keys to The same path also answers `PUT` (same body), `GET` (the stored settings, with both keys masked to their last four characters) and `DELETE` (stop exporting). Changes apply from the next chat turn; there is no restart. -You can also set it in the RAGFlow web UI, where the Langfuse settings are: avatar, **API**, scroll to the bottom, **Future AGI** card, **Configuration**. The dialog has the same fields. It never fills in the keys (the server only returns them masked), so enter both keys each time you save. The dialog was checked with RAGFlow's own formatter and linter only; it was not rendered in a browser. +You can also set it in the RAGFlow web UI, where the Langfuse settings are: avatar, **API**, scroll to the bottom, **Future AGI** card, **Configuration**. The dialog has the same fields. It never fills in the keys (the server only returns them masked), so enter both keys each time you save. The card and dialog were type-checked, linted and rendered in a headless browser with the settings API mocked (empty, saved with masked keys, and a rejected save); they were not opened against a running RAGFlow server. The exporter sends OTLP/HTTP JSON, uncompressed (the Future AGI collector does not accept gzip), with the resource attributes `project_name`, `project_type=observe` and `service.name=ragflow`. The trace is sent when the chat turn ends. @@ -136,7 +136,7 @@ Tracing never changes the chat: - Fork only. Stock RAGFlow images do not have the exporter. It is not in an upstream release. - One Observe project per tenant. All chat assistants of a tenant share it. - Not run: the full RAGFlow Docker stack and its web UI, knowledge-base retrieval against a real document engine (the retrieval span maps the same chunk fields RAGFlow's knowledge-base retrieval returns; that mapping is unit tested), the embedded chatbot endpoint, agentic reasoning mode, MySQL, and the hosted Future AGI service. -- The settings dialog is new and was not rendered; if it misbehaves, configure with the API. +- The settings dialog is new and was rendered only headless with a mocked settings API, not against a running server; if it misbehaves, configure with the API. - Agent canvases (RAGFlow's agent builder) are not traced by this exporter. ## Verification (2026-10-20) @@ -145,11 +145,11 @@ What ran, on a Mac with Go 1.27 (darwin/arm64, `CGO_ENABLED=0`): - **RAGFlow's Go server path, in process.** RAGFlow's own services (model provider, chat assistant, chat session completion with web search, OpenAI-compatible endpoint) on SQLite, with a real model, real Tavily and a real Future AGI collector. Results and trace ids are in the [fork pull request](https://github.com/future-agi/ragflow/pull/1) (2026-10-17 runs, fork branch and merged onto `v1.0.0-rc2`). - **Unit tests** for the exporter, the settings service and the settings handler, beside RAGFlow's existing Langfuse tests, and `go vet` and `gofmt` on the touched packages. -- **Formatter and linter** (`oxfmt`, `oxlint`, the versions RAGFlow's pre-commit uses) on the settings dialog files. +- **Web checks** on the settings card files: formatter and linter (`oxfmt`, `oxlint`, the versions RAGFlow's pre-commit uses) clean; `tsc --noEmit` adds no type errors (every project-wide error it reports is already on the base commit); and the card rendered in a headless browser with the settings API mocked, in three states: empty, saved (keys shown only as their last four characters) and a rejected save (the `invalid Future AGI keys` error). What did not run: -- The full RAGFlow Docker stack (about 16 GB of memory; the machine could not spare it) and the RAGFlow web UI, so the settings dialog was not opened and the TypeScript was not type-checked. +- The full RAGFlow Docker stack (about 16 GB of memory; the machine could not spare it) and the RAGFlow web UI against a running server, so the settings dialog was not used end to end. - Knowledge-base retrieval against Elasticsearch or Infinity, the embedded chatbot endpoint, agentic reasoning mode, MySQL, and the hosted Future AGI service. ## Troubleshooting From fbb314f4dc6f4550d7b55dd2dce8006bf4eb0c5c Mon Sep 17 00:00:00 2001 From: Nikhil Pareek <8347993+nik13@users.noreply.github.com> Date: Thu, 29 Oct 2026 06:12:23 -0700 Subject: [PATCH 4/9] docs(ragflow): replace full-stack promises with prototype status Co-Authored-By: Claude Code --- src/lib/integrations.mjs | 1 + .../docs/integrations/no-code/ragflow.mdx | 167 +++--------------- 2 files changed, 23 insertions(+), 145 deletions(-) diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index 040dfe275..2a201f562 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -26,6 +26,7 @@ export const integrationCategories = [ /** @type {ReadonlyArray} */ export const integrations = [ + { id: 'ragflow', name: 'RAGFlow', href: '/docs/integrations/no-code/ragflow', category: 'apps', summary: 'Review fork-only exporter availability and development scope.', method: 'Integration status', logo: 'generic-framework' }, { id: 'cognee', name: 'Cognee', href: '/docs/integrations/traceai/cognee', category: 'frameworks', summary: 'Export native memory-operation spans with a privacy filter.', method: 'Native OTLP', logo: 'generic-framework' }, { id: 'openinference', name: 'OpenInference', href: '/docs/integrations/import/openinference', category: 'frameworks', summary: 'Send the qualified Python OpenAI instrumentor spans over OTLP.', method: 'OpenInference SDK', logo: 'generic-framework' }, { id: 'oh-my-pi', name: 'Oh My Pi', href: '/docs/integrations/coding-agents/oh-my-pi', category: 'coding', summary: 'Trace omp sessions with the version-scoped local hook.', method: 'omp hook', logo: 'generic-framework' }, diff --git a/src/pages/docs/integrations/no-code/ragflow.mdx b/src/pages/docs/integrations/no-code/ragflow.mdx index 1f6905d05..71dae1856 100644 --- a/src/pages/docs/integrations/no-code/ragflow.mdx +++ b/src/pages/docs/integrations/no-code/ragflow.mdx @@ -1,164 +1,41 @@ --- -title: "Send RAGFlow chats to Observe" -description: "Save Future AGI keys for a RAGFlow tenant on a RAGFlow build from the future-agi fork, and every chat turn becomes a trace in Observe: the turn, the retrieval with chunk ids and scores, and the answer call with model and tokens. Fork only until it is accepted upstream." +title: "RAGFlow integration status" +description: "Current availability and verified development scope of the fork-only RAGFlow Future AGI exporter. Stock images do not include this integration." --- -## About +## Availability -RAGFlow is an open-source RAG engine: chat assistants answer from knowledge bases (and optionally web search) with citations. RAGFlow already has a per-tenant Langfuse integration. The Future AGI exporter sits next to it: a tenant saves Future AGI keys once, and from then on every chat turn of that tenant's chat assistants lands in an Observe project as one trace. +The Future AGI exporter is a **fork-only prototype**, tracked in [future-agi/ragflow PR #1](https://github.com/future-agi/ragflow/pull/1). It is not part of stock RAGFlow images or an upstream release. This is a status page, not a supported installation guide; it does not prescribe a Docker image build, database migration or production onboarding. -You configure RAGFlow only. Chat assistants do not change, and there is nothing to install in your application. +As checked on **2026-10-29**, GitHub's latest RAGFlow release is [v1.0.0-rc2](https://github.com/infiniflow/ragflow/releases/tag/v1.0.0-rc2), published 2026-10-16. The exporter branch `feat/th-8233-futureagi-export` is at `be76831f046c892bd3c85faef91dc334e1aabf2a`; the fork PR remains open. No traceAI package installation adds this exporter to a stock RAGFlow deployment. -| | | -| --- | --- | -| Tested with | The fork branch [`future-agi/ragflow` `feat/th-8233-futureagi-export`](https://github.com/future-agi/ragflow/pull/1), which is RAGFlow `main` at `2400ca8` (the `v1.0.0-rc1` Go tree) plus the exporter; and the same commits merged onto RAGFlow `v1.0.0-rc2` (released 2026-10-16, the newest release on GitHub; still a release candidate, there is no `v1.0.0` yet). Go 1.27. | -| Not supported | Stock RAGFlow images and releases (they do not contain the exporter), and the Python-era `v0.x` line (latest `v0.27.2`). | -| Future AGI side | A self-hosted Future AGI stack built from `dev` (collector on `/tracer/v1/traces`). | -| Models used | A real GPT model through RAGFlow's **OpenAI-API-Compatible** model provider. Web search through RAGFlow's Tavily provider. | - - -Alpha, fork only. What ran: RAGFlow's own services in process, with real model and Tavily calls, exporting to a real Future AGI collector: the model provider and chat assistant services, the chat session completion (`/api/v1/chat/completions`, the path the RAGFlow web chat uses; streamed, with web search), the OpenAI-compatible endpoint (`/api/v1/openai/{chat_id}/chat/completions`, not streamed), a chat whose model key is wrong, hidden content, wrong Future AGI keys and a collector that refuses connections, on both RAGFlow trees above. SQLite stood in for MySQL and no document engine was running. What did not run: the full RAGFlow Docker stack and its web UI against a running server (it needs more memory than our test machine had; the settings card was rendered headless with the settings API mocked instead), knowledge-base retrieval against Elasticsearch or Infinity, the embedded chatbot endpoint (`/api/v1/chatbots/{id}/completions`), agentic reasoning mode, and the hosted Future AGI service. - - -## Where the exporter comes from - -The exporter is in the [future-agi/ragflow](https://github.com/future-agi/ragflow) fork, next to RAGFlow's Langfuse client in the Go API server: a `tenant_futureagi` table, a `/api/v1/futureagi/api-key` settings API shaped like `/api/v1/langfuse/api-key`, and a few hooks in the chat pipeline. It has not been submitted to `infiniflow/ragflow` yet. - -RAGFlow's own OpenTelemetry settings (the `otel` block, `OTEL_HOST` and `OTEL_PORT`) are not used. They have no field for headers, no exporter is wired to them in `v1.0.0-rc1` or `v1.0.0-rc2`, and the spans RAGFlow creates for its agent graph engine carry no model, prompt or token data. - -## Before you start - -- A Future AGI API key and secret key, and the name of the Observe project you want the traces in. The self-hosted stack we tested created the project on the first trace. If you are not sure your workspace does the same, create the project first. -- A RAGFlow server built from the fork, and a RAGFlow API key (or login token) of the account that owns the chat assistants. Keys are saved per tenant, the same as Langfuse keys: the account that owns a chat assistant decides where its chats are traced. - -## Build RAGFlow from the fork - -Build the image the way RAGFlow's [Build RAGFlow Docker image](https://github.com/infiniflow/ragflow/blob/main/docs/develop/build_docker_image.mdx) guide describes, from the fork branch: - -```bash -git clone --branch feat/th-8233-futureagi-export https://github.com/future-agi/ragflow.git -cd ragflow -docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local . -# then set RAGFLOW_IMAGE=ragflow:go-local in docker/.env -cd docker && docker compose -f docker-compose.yml up -d -``` - -The container runs RAGFlow's database migration at start, which creates the `tenant_futureagi` table. We did not build or run this image ourselves; the runs above used the same Go code in process. - -## Configure - -Save the keys once per tenant with the settings API: - -```bash -curl -X POST "http:///api/v1/futureagi/api-key" \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{ - "api_key": "", - "secret_key": "", - "project_name": "my-ragflow-app", - "endpoint": "https://api.futureagi.com", - "redact": false - }' -``` - -| Field | Required | Meaning | -| --- | --- | --- | -| `api_key` | Yes | Future AGI API key. Sent as the `X-Api-Key` header. | -| `secret_key` | Yes | Future AGI secret key. Sent as the `X-Secret-Key` header. | -| `project_name` | Yes | The Observe project for every chat of this tenant. | -| `endpoint` | No | Default `https://api.futureagi.com`. For a self-hosted collector, for example `http://collector:4318`. RAGFlow appends `/tracer/v1/traces`. | -| `redact` | No | Default `false`. `true` hides content. See [Privacy](#privacy). | - -Before it stores anything, RAGFlow posts an empty trace export with the keys to the collector. Wrong keys fail the save with `invalid Future AGI keys`, an unreachable collector with `cannot verify the Future AGI keys: ...`, and the stored settings stay as they were. - -The same path also answers `PUT` (same body), `GET` (the stored settings, with both keys masked to their last four characters) and `DELETE` (stop exporting). Changes apply from the next chat turn; there is no restart. - -You can also set it in the RAGFlow web UI, where the Langfuse settings are: avatar, **API**, scroll to the bottom, **Future AGI** card, **Configuration**. The dialog has the same fields. It never fills in the keys (the server only returns them masked), so enter both keys each time you save. The card and dialog were type-checked, linted and rendered in a headless browser with the settings API mocked (empty, saved with masked keys, and a rejected save); they were not opened against a running RAGFlow server. - -The exporter sends OTLP/HTTP JSON, uncompressed (the Future AGI collector does not accept gzip), with the resource attributes `project_name`, `project_type=observe` and `service.name=ragflow`. The trace is sent when the chat turn ends. +## Verified development scope -## What you see in Observe +The recorded 2026-10-17 runs exercised RAGFlow's Go services **in process**, using SQLite, an OpenAI-compatible model, Tavily web search and a self-hosted Future AGI collector. They cover the chat-session completion service and the OpenAI-compatible completion endpoint, success and model-key errors, redacted content, rejected Future AGI keys and collector connection failures. They are not full-stack deployment receipts. -One trace per chat turn, from every chat entry point: the RAGFlow web chat and `/api/v1/chat/completions`, the OpenAI-compatible endpoint `/api/v1/openai/{chat_id}/chat/completions`, and embedded chatbots `/api/v1/chatbots/{id}/completions` (the last one was not run). - -| Span | What it is | +| Component | Evidence scope | | --- | --- | -| `ragflow.chat` (root, `chain`) | The turn. Input is the user's question, output the answer. ERROR when RAGFlow answered with an error. | -| `ragflow.retrieval` (`retriever`) | When the chat retrieved (knowledge bases and/or web search). Input is the search question. Each retrieved chunk is a `retrieval.documents.N.document.*` entry: chunk id, similarity score, chunk text, and metadata (document id, document name, knowledge base id, vector and term similarity, URL for web results). Also `ragflow.retrieval.chunk_count`, `top_n`, `top_k`, `similarity_threshold`, `vector_similarity_weight`, `ragflow.kb_count`, and the rerank model when one is set. | -| `ragflow.llm` (`llm`) | The answer call. `llm.model_name` / `gen_ai.request.model`, `gen_ai.provider.name` (the RAGFlow model provider), the input messages (system prompt with the retrieved knowledge, then the conversation), the answer, and prompt / completion / total tokens. | - -Root attributes: `session.id` and `gen_ai.conversation.id` (the RAGFlow conversation id; the chat assistant id on the OpenAI-compatible endpoint, which has no conversation), `user.id` and `ragflow.tenant_id` (the tenant id, not an end user), `ragflow.chat_id`, `ragflow.pipeline` (`rag`, `solo` for assistants without retrieval, `other`), `ragflow.stream`. - -Token counts are the ones RAGFlow computes itself with the `cl100k` tokenizer, the same numbers it reports to Langfuse (`ragflow.usage.source=ragflow_cl100k_count`). They can differ slightly from the provider's own count. - -Real example from the tested chat (web search on, streamed): three spans. `ragflow.chat` 6.2 s, `ragflow.retrieval` 2.3 s with six Tavily results (ids, scores 0.87 to 0.90, page text), `ragflow.llm` 3.8 s with `gpt-6-luna` and 1,844 / 82 tokens. The OpenAI-compatible call on an assistant without retrieval is two spans: `ragflow.chat` and `ragflow.llm` (39 / 38 tokens). - -Not captured: the steps inside agentic reasoning mode and SQL answers (only the `ragflow.chat` span), query refinement and keyword-extraction model calls, embedding and rerank calls (no separate spans), RAGFlow agent canvases, document ingestion, cost when the model is unknown to Future AGI, and a second Observe project for the same tenant. - -## Privacy - -Content is exported by default, like RAGFlow's Langfuse integration and the traceAI convention: questions, answers, the prompt sent to the model (including the retrieved knowledge), chunk text and document names. - -To hide content for a tenant, save the settings with `"redact": true`. With redact on, the export keeps the trace shape, span names, model, token counts, timings, status, chunk ids and similarity scores, and drops every question, answer, message, system prompt, chunk text and document name. Web-search chunk ids, which RAGFlow builds from the page URL, are replaced by a stable hash, and error text is replaced by a fixed line. - -This was checked, not assumed. A unique marker and an email address were put into the question of a web-search chat, a failing chat and an OpenAI-compatible call with redact on. Every stored column for those traces (ClickHouse `spans` including resource attributes, span events and the extra-attributes column, plus `traces`, `trace_sessions` and `end_users`) was searched: neither was found, nor the question text, the system prompt, a web result host or the model's error text. With the defaults, the marker, question and system prompt were found in the stored spans. +| Fork based on RAGFlow main `2400ca8` | Go service execution with real model and web-search calls | +| Exporter changes applied to `v1.0.0-rc2` | Separate in-process service run | +| Exporter and settings service/handler | Unit tests, `go vet` and formatting checks | +| Settings card | Type/lint checks and a headless render against mocked settings APIs | -In both modes: +Trace ids and run details are retained in the [fork PR](https://github.com/future-agi/ragflow/pull/1). No mocked UI result is presented as a real browser-to-database onboarding pass. -- Error text has URLs, IP addresses, email addresses, file paths, and the server's user and host names masked, and is capped at 512 characters. For example, a model call rejected with a wrong key is stored as `API request failed with status 401: {"error":"Invalid API key"}`, without the model host. -- The server's home directory is replaced with `~` in every exported value. -- The resource carries only `project_name`, `project_type` and `service.name`. No host name, user name or process path. A search of every stored column for the OS user name, host name, home directory, the model host and port, and all keys used found none of them. -- `user.id` is the RAGFlow tenant id and `session.id` the RAGFlow conversation or assistant id. Both are opaque ids and stay when redact is on. +## What the prototype exports -The Future AGI keys are stored as plain columns in `tenant_futureagi`, the same protection RAGFlow gives Langfuse keys today. `GET` returns them masked. +For the exercised chat paths, a turn produces `ragflow.chat` (chain), an optional `ragflow.retrieval` child for web search, and `ragflow.llm` for the answer call. The model span carries the model and RAGFlow's token counts. These counts use RAGFlow's tokenizer (`ragflow.usage.source=ragflow_cl100k_count`), not provider billing totals. -## Errors and failure behaviour +The exporter sends uncompressed OTLP/HTTP JSON to `/tracer/v1/traces`, with `project_name`, `project_type=observe` and `service.name=ragflow`. Configuration is per tenant in `tenant_futureagi`; it is separate from RAGFlow's Langfuse integration and its `OTEL_HOST` settings. The tested route is self-hosted Future AGI, not the hosted service. -A failed turn is marked ERROR on `ragflow.chat`, and on `ragflow.llm` when the model call failed. The tested chat with a wrong model key gave two ERROR spans, both with `API request failed with status 401: {"error":"Invalid API key"}`. +## Privacy and failure behavior -Tracing never changes the chat: +**Content is on by default in the prototype.** Questions, answers, prompts and retrieved text can leave RAGFlow. The per-tenant `redact=true` setting removes those values and substitutes fixed error text while retaining ids, model, token counts, status and timing. The recorded redacted runs scanned stored trace columns for prompt markers and email addresses; no matches were found. That receipt applies to the in-process paths above, not every RAGFlow feature. -- **Wrong keys at save time.** The save fails; nothing is stored. -- **Collector down later.** Chats answered normally and in their usual time (6 s for the web-search chat), the traces were dropped, and RAGFlow logged at most one warning a minute: `Future AGI: chat trace dropped; chats are not affected` with `reason: Future AGI collector unreachable`. -- **Busy collector.** Each tenant has one background exporter with a queue of 1,024 traces and a 5 s request timeout. A full queue drops the trace instead of waiting. -- **Shutdown.** When the API server stops, it waits up to 2 s for queued traces to be sent. A hard kill can lose the last traces. +Future AGI keys are stored in plaintext database columns; the settings GET response masks them. Protect the database and backups accordingly. Each tenant has a bounded 1,024-trace queue and a 5-second request timeout; a full queue or unavailable collector drops traces rather than blocking chat. Shutdown allows up to 2 seconds to flush, so a hard kill or slow collector can lose traces. -## How this differs from related integrations +## Required before an installation guide -- **RAGFlow's Langfuse integration.** Both can be on at once; they are independent. The Langfuse client is only called from the OpenAI-compatible endpoint and records a generation whose output is RAGFlow's timing block; the Future AGI exporter covers every chat entry point, records the answer text and adds the retrieval span. Future AGI does not accept RAGFlow's Langfuse payloads. -- **RAGFlow's OpenTelemetry settings (`OTEL_HOST`).** Do not point them at Future AGI: they cannot send the API key headers or `project_name`, and nothing exports chat spans through them. -- **traceAI packages ([LangChain](/docs/integrations/traceai/langchain) and others).** Those instrument code you write yourself. RAGFlow is a server with its own Go pipeline, so use this exporter instead of a traceAI package. -- **Other no-code builders (Dify, Flowise, Langflow).** Each has its own integration; this page covers RAGFlow only. +A supported onboarding guide needs an exact fork-image build and Docker Compose run using the real database and document engine, migration verification, and a browser session that saves settings and sends a traced chat through the running server. Those deployment receipts are outstanding, so the draft remains held. -## Limits and what was not tested - -- Fork only. Stock RAGFlow images do not have the exporter. It is not in an upstream release. -- One Observe project per tenant. All chat assistants of a tenant share it. -- Not run: the full RAGFlow Docker stack and its web UI, knowledge-base retrieval against a real document engine (the retrieval span maps the same chunk fields RAGFlow's knowledge-base retrieval returns; that mapping is unit tested), the embedded chatbot endpoint, agentic reasoning mode, MySQL, and the hosted Future AGI service. -- The settings dialog is new and was rendered only headless with a mocked settings API, not against a running server; if it misbehaves, configure with the API. -- Agent canvases (RAGFlow's agent builder) are not traced by this exporter. - -## Verification (2026-10-20) - -What ran, on a Mac with Go 1.27 (darwin/arm64, `CGO_ENABLED=0`): - -- **RAGFlow's Go server path, in process.** RAGFlow's own services (model provider, chat assistant, chat session completion with web search, OpenAI-compatible endpoint) on SQLite, with a real model, real Tavily and a real Future AGI collector. Results and trace ids are in the [fork pull request](https://github.com/future-agi/ragflow/pull/1) (2026-10-17 runs, fork branch and merged onto `v1.0.0-rc2`). -- **Unit tests** for the exporter, the settings service and the settings handler, beside RAGFlow's existing Langfuse tests, and `go vet` and `gofmt` on the touched packages. -- **Web checks** on the settings card files: formatter and linter (`oxfmt`, `oxlint`, the versions RAGFlow's pre-commit uses) clean; `tsc --noEmit` adds no type errors (every project-wide error it reports is already on the base commit); and the card rendered in a headless browser with the settings API mocked, in three states: empty, saved (keys shown only as their last four characters) and a rejected save (the `invalid Future AGI keys` error). - -What did not run: - -- The full RAGFlow Docker stack (about 16 GB of memory; the machine could not spare it) and the RAGFlow web UI against a running server, so the settings dialog was not used end to end. -- Knowledge-base retrieval against Elasticsearch or Infinity, the embedded chatbot endpoint, agentic reasoning mode, MySQL, and the hosted Future AGI service. - -## Troubleshooting - -| What you see | What it means | -| --- | --- | -| `invalid Future AGI keys` when saving | The collector rejected the API key / secret key pair. Nothing was stored. | -| `cannot verify the Future AGI keys: Future AGI collector unreachable` | RAGFlow cannot reach `endpoint`. Check the URL; RAGFlow adds `/tracer/v1/traces` itself. | -| `Future AGI: chat trace dropped; chats are not affected` in the RAGFlow log | The collector stopped answering, or answered with an error (the `reason` field says which). Chats are unaffected. | -| No traces and no log line | No settings are saved for the tenant that owns the chat assistant (`GET /api/v1/futureagi/api-key` with that account), or this RAGFlow build does not have the exporter. | -| Traces have no inputs or outputs | `redact` is `true` for the tenant. | -| Agentic or SQL answers have only one span | Expected: those paths are traced as the `ragflow.chat` span only. | +The current scope excludes MySQL deployment, Elasticsearch/Infinity knowledge-base retrieval, embedded chatbots, agentic reasoning, agent canvases and hosted Future AGI. SQLite service tests and mocked settings responses do not establish those paths. Stock-image support additionally requires an upstream distribution that contains the exporter. From 3f1195ab767a79dc71026f121b3a12969edd9ed7 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 8 Nov 2026 17:58:15 -0800 Subject: [PATCH 5/9] docs(ragflow): correct release availability without lifting hold Replace the outdated rc2 latest-release statement with the verified v1.0.0 availability. The integration remains held pending real deployment qualification. Co-Authored-By: Claude Code --- src/pages/docs/integrations/no-code/ragflow.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/integrations/no-code/ragflow.mdx b/src/pages/docs/integrations/no-code/ragflow.mdx index 71dae1856..5c728145c 100644 --- a/src/pages/docs/integrations/no-code/ragflow.mdx +++ b/src/pages/docs/integrations/no-code/ragflow.mdx @@ -7,7 +7,7 @@ description: "Current availability and verified development scope of the fork-on The Future AGI exporter is a **fork-only prototype**, tracked in [future-agi/ragflow PR #1](https://github.com/future-agi/ragflow/pull/1). It is not part of stock RAGFlow images or an upstream release. This is a status page, not a supported installation guide; it does not prescribe a Docker image build, database migration or production onboarding. -As checked on **2026-10-29**, GitHub's latest RAGFlow release is [v1.0.0-rc2](https://github.com/infiniflow/ragflow/releases/tag/v1.0.0-rc2), published 2026-10-16. The exporter branch `feat/th-8233-futureagi-export` is at `be76831f046c892bd3c85faef91dc334e1aabf2a`; the fork PR remains open. No traceAI package installation adds this exporter to a stock RAGFlow deployment. +RAGFlow [v1.0.0](https://github.com/infiniflow/ragflow/releases/tag/v1.0.0) does not include this exporter. No traceAI package installation adds it to a stock RAGFlow deployment. ## Verified development scope From 1a9e1964871b252022415fba24e2a28e11074f4d Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Sun, 8 Nov 2026 19:40:34 -0800 Subject: [PATCH 6/9] docs(ragflow): replace held diary with qualified native settings guide Document the pinned fork image and real settings flow, retain stock-image/version/privacy boundaries, and add customer-wording and built-page regressions. Production image, MySQL/Infinity ingestion and retrieval, browser onboarding, real model chat and Cloud OTLP acceptance have completed. Co-Authored-By: Claude Code --- scripts/integrations.regression.cjs | 21 +++++ scripts/integrations.test.mjs | 1 + scripts/ragflow-page.test.mjs | 42 +++++++++ src/lib/integrations.mjs | 2 +- .../docs/integrations/no-code/ragflow.mdx | 87 ++++++++++++++----- 5 files changed, 129 insertions(+), 24 deletions(-) create mode 100644 scripts/ragflow-page.test.mjs diff --git a/scripts/integrations.regression.cjs b/scripts/integrations.regression.cjs index f01289a84..7c39201e3 100644 --- a/scripts/integrations.regression.cjs +++ b/scripts/integrations.regression.cjs @@ -220,6 +220,27 @@ function luminance(rgb) { return rgb.map(v => v / 255).map(v => v <= 0.04045 ? v } return { overview: true, entries: integrations.length }; }); + await record('RAGFlow customer guide renders native settings and pinned build', async () => { + const context = await createDocsContext(browser, BASE, { viewport: { width: 1440, height: 1000 }, reducedMotion: 'reduce' }); + try { + const page = await context.newPage(); + const response = await page.goto(BASE + '/docs/integrations/no-code/ragflow', { waitUntil: 'networkidle' }); + assert.equal(response.status(), 200); + assert.equal((await page.locator('h1').innerText()).trim(), 'RAGFlow'); + const text = await page.locator('body').innerText(); + assert.ok(text.includes('Configure trace export')); + assert.ok(text.includes('User settings → API')); + assert.ok(text.includes('plaintext database columns')); + assert.ok(text.includes('ragflow.retrieval')); + assert.doesNotMatch(text, /Verified development scope|fork-only prototype|Required before an installation guide/i); + const build = page.locator('pre').filter({ hasText: 'docker buildx build' }); + assert.equal(await build.count(), 1); + assert.ok((await build.innerText()).includes('60492deba70ea7431e13c23de271ab10c3aa0aea')); + assert.equal(await page.locator('table').count(), 1); + await page.screenshot({ path: path.join(OUT, 'ragflow-customer-guide.png'), fullPage: true }); + return { pathname: new URL(page.url()).pathname, settingsTable: true, pinnedBuild: true }; + } finally { await context.close(); } + }); await browser.close(); console.log(JSON.stringify({ tests: results.length, failed: results.filter(r => r.status === 'FAIL').length })); if (results.some(r => r.status === 'FAIL')) process.exitCode = 1; diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index d099b0d36..d876fa43a 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -1,3 +1,4 @@ +import './ragflow-page.test.mjs'; import './auto-page.test.mjs'; import './pi-plugin-page.test.mjs'; import './openclaw-package-page.test.mjs'; diff --git a/scripts/ragflow-page.test.mjs b/scripts/ragflow-page.test.mjs new file mode 100644 index 000000000..3e3763d9c --- /dev/null +++ b/scripts/ragflow-page.test.mjs @@ -0,0 +1,42 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { integrations } from '../src/lib/integrations.mjs'; + +const page = readFileSync(new URL('../src/pages/docs/integrations/no-code/ragflow.mdx', import.meta.url), 'utf8'); +const source = '60492deba70ea7431e13c23de271ab10c3aa0aea'; + +test('RAGFlow guide scopes onboarding to the pinned fork, not a stock image', () => { + assert.match(page, /Stock RAGFlow \*\*v1\.0\.0\*\* images do not include this exporter/); + assert.ok(page.includes(`checkout --detach ${source}`)); + assert.ok(page.includes(`fetch --depth 200 origin ${source} tag v1.0.0-rc1`)); + assert.match(page, /docker buildx build --load --network host --target production/); + assert.match(page, /Linux x86-64/); + assert.match(page, /MySQL, Infinity, MinIO, Kvrocks and NATS/); + assert.match(page, /separate deployment and database/); + assert.match(page, /Do not disable the database version guard/); + assert.doesNotMatch(page, /pip install|npx .*traceai|copy.*(?:bridge|exporter class)/i); + const entry = integrations.find(item => item.id === 'ragflow'); + assert.equal(entry?.method, 'RAGFlow settings'); + assert.match(entry?.summary ?? '', /fork/); +}); + +test('RAGFlow guide uses the native settings flow and preserves privacy constraints', () => { + for (const text of ['User settings → API', '**Configuration**', '**API key**', '**Secret key**', '**Observe project**', '**Endpoint**', '**Redact content**', '**Save**']) { + assert.ok(page.includes(text), text); + } + assert.match(page, /https:\/\/api\.futureagi\.com/); + assert.match(page, /\/tracer\/v1\/traces/); + assert.match(page, /on by default/); + assert.match(page, /plaintext database columns/); + assert.match(page, /enter both keys again/); + assert.match(page, /not provider billing totals/); + assert.match(page, /not a durable audit log/); + for (const span of ['ragflow.chat', 'ragflow.retrieval', 'ragflow.llm']) assert.ok(page.includes(span)); +}); + +test('RAGFlow customer page does not regress to a prototype or verification diary', () => { + assert.doesNotMatch(page, /prototype|verified development|mocked|SQLite|E2B|sandbox|release gates|publication hold|TH-8233|trace ids|2026-\d{2}-\d{2}|PR #|pull\/1\)/i); + assert.match(page, /## Configure trace export/); + assert.match(page, /## Send a chat and inspect its trace/); +}); diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index a91ccb3ca..01a122c9b 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -26,7 +26,7 @@ export const integrationCategories = [ /** @type {ReadonlyArray} */ export const integrations = [ - { id: 'ragflow', name: 'RAGFlow', href: '/docs/integrations/no-code/ragflow', category: 'apps', summary: 'Review fork-only exporter availability and development scope.', method: 'Integration status', logo: 'generic-framework' }, + { id: 'ragflow', name: 'RAGFlow', href: '/docs/integrations/no-code/ragflow', category: 'apps', summary: 'Trace chat turns, retrieval and model calls from the Future AGI RAGFlow fork.', method: 'RAGFlow settings', logo: 'generic-framework' }, { id: 'traceai-auto', name: 'Zero-code Node.js', href: '/docs/integrations/traceai/auto', category: 'frameworks', summary: 'Trace supported Node.js AI calls with one startup preload and no tracing imports.', method: 'traceAI preload', logo: 'generic-framework', aliases: ['@traceai/auto', 'Node.js', 'TypeScript', 'JavaScript', 'zero code', 'auto instrumentation'] }, { id: 'a2a-go', name: 'A2A Go', href: '/docs/integrations/traceai/go/a2a', category: 'frameworks', summary: 'Trace Go agent-to-agent calls on clients and servers.', method: 'traceAI SDK', logo: 'generic-framework' }, { id: 'vitest', name: 'Vitest', href: '/docs/integrations/frameworks/vitest', category: 'frameworks', summary: 'Trace test runs and workers with native OpenTelemetry.', method: 'Native OTLP', logo: 'generic-framework', aliases: ['Vitest tests'] }, diff --git a/src/pages/docs/integrations/no-code/ragflow.mdx b/src/pages/docs/integrations/no-code/ragflow.mdx index 5c728145c..459c671c3 100644 --- a/src/pages/docs/integrations/no-code/ragflow.mdx +++ b/src/pages/docs/integrations/no-code/ragflow.mdx @@ -1,41 +1,82 @@ --- -title: "RAGFlow integration status" -description: "Current availability and verified development scope of the fork-only RAGFlow Future AGI exporter. Stock images do not include this integration." +title: "RAGFlow" +description: "Configure Future AGI trace export in a self-hosted, Future AGI-enabled RAGFlow deployment." --- -## Availability +Send RAGFlow chat turns, retrieved documents and model calls to Future AGI Observe from RAGFlow's settings. You do not need to add instrumentation code to your chats. -The Future AGI exporter is a **fork-only prototype**, tracked in [future-agi/ragflow PR #1](https://github.com/future-agi/ragflow/pull/1). It is not part of stock RAGFlow images or an upstream release. This is a status page, not a supported installation guide; it does not prescribe a Docker image build, database migration or production onboarding. +## Prerequisites -RAGFlow [v1.0.0](https://github.com/infiniflow/ragflow/releases/tag/v1.0.0) does not include this exporter. No traceAI package installation adds it to a stock RAGFlow deployment. +- A Linux x86-64 self-hosted deployment of the [Future AGI RAGFlow fork](https://github.com/future-agi/ragflow/tree/60492deba70ea7431e13c23de271ab10c3aa0aea), using the Go backend, MySQL, Infinity, MinIO, Kvrocks and NATS. +- A chat model and an embedding model configured in RAGFlow, with your own provider credentials. +- Your Future AGI API key and secret key, available in **Settings → API keys**, and an Observe project name. -## Verified development scope +Stock RAGFlow **v1.0.0** images do not include this exporter. Installing a traceAI package in a stock image does not add the **Future AGI** settings card. -The recorded 2026-10-17 runs exercised RAGFlow's Go services **in process**, using SQLite, an OpenAI-compatible model, Tavily web search and a self-hosted Future AGI collector. They cover the chat-session completion service and the OpenAI-compatible completion endpoint, success and model-key errors, redacted content, rejected Future AGI keys and collector connection failures. They are not full-stack deployment receipts. +### Build the Future AGI-enabled image -| Component | Evidence scope | -| --- | --- | -| Fork based on RAGFlow main `2400ca8` | Go service execution with real model and web-search calls | -| Exporter changes applied to `v1.0.0-rc2` | Separate in-process service run | -| Exporter and settings service/handler | Unit tests, `go vet` and formatting checks | -| Settings card | Type/lint checks and a headless render against mocked settings APIs | +If your deployment does not already use the fork, build this pinned image with Docker Buildx: -Trace ids and run details are retained in the [fork PR](https://github.com/future-agi/ragflow/pull/1). No mocked UI result is presented as a real browser-to-database onboarding pass. +```bash +git init ragflow-futureagi +git -C ragflow-futureagi remote add origin https://github.com/future-agi/ragflow.git +git -C ragflow-futureagi fetch --depth 200 origin 60492deba70ea7431e13c23de271ab10c3aa0aea tag v1.0.0-rc1 +git -C ragflow-futureagi checkout --detach 60492deba70ea7431e13c23de271ab10c3aa0aea +docker buildx build --load --network host --target production --tag ragflow-futureagi:60492deb --file ragflow-futureagi/Dockerfile ragflow-futureagi +``` -## What the prototype exports +Use `ragflow-futureagi:60492deb` as the application image in your self-hosted RAGFlow deployment. Keep its database, document engine, storage, cache and queue services configured using the fork's [deployment configuration](https://github.com/future-agi/ragflow/tree/60492deba70ea7431e13c23de271ab10c3aa0aea/docker). This image runs the Go services and applies database migrations before starting them. -For the exercised chat paths, a turn produces `ragflow.chat` (chain), an optional `ragflow.retrieval` child for web search, and `ragflow.llm` for the answer call. The model span carries the model and RAGFlow's token counts. These counts use RAGFlow's tokenizer (`ragflow.usage.source=ragflow_cl100k_count`), not provider billing totals. +Use a separate deployment and database for this pinned build; do not replace a newer RAGFlow installation or downgrade its database. Keep the release tag and Git history when building so the image's version can be compared with the database version. Do not disable the database version guard to make a mismatched deployment start. -The exporter sends uncompressed OTLP/HTTP JSON to `/tracer/v1/traces`, with `project_name`, `project_type=observe` and `service.name=ragflow`. Configuration is per tenant in `tenant_futureagi`; it is separate from RAGFlow's Langfuse integration and its `OTEL_HOST` settings. The tested route is self-hosted Future AGI, not the hosted service. +## Configure trace export -## Privacy and failure behavior +1. In RAGFlow, open **User settings → API**. +2. On the **Future AGI** card, select **Configuration**. +3. Fill in the following fields: -**Content is on by default in the prototype.** Questions, answers, prompts and retrieved text can leave RAGFlow. The per-tenant `redact=true` setting removes those values and substitutes fixed error text while retaining ids, model, token counts, status and timing. The recorded redacted runs scanned stored trace columns for prompt markers and email addresses; no matches were found. That receipt applies to the in-process paths above, not every RAGFlow feature. + | Field | Value | + | --- | --- | + | **API key** | Your Future AGI API key | + | **Secret key** | The matching Future AGI secret key | + | **Observe project** | The project name to use for these traces | + | **Endpoint** | `https://api.futureagi.com` for Future AGI Cloud, or your self-hosted collector origin | + | **Redact content** | Enable to omit question, answer, prompt and retrieved text | -Future AGI keys are stored in plaintext database columns; the settings GET response masks them. Protect the database and backups accordingly. Each tenant has a bounded 1,024-trace queue and a 5-second request timeout; a full queue or unavailable collector drops traces rather than blocking chat. Shutdown allows up to 2 seconds to flush, so a hard kill or slow collector can lose traces. +4. Select **Save**. RAGFlow checks the collector connection and credentials before saving. -## Required before an installation guide +Enter the collector origin in **Endpoint**, not a Langfuse URL. RAGFlow sends OTLP/HTTP to `/tracer/v1/traces` and manages the authentication headers itself. The Future AGI and Langfuse configurations are independent. -A supported onboarding guide needs an exact fork-image build and Docker Compose run using the real database and document engine, migration verification, and a browser session that saves settings and sends a traced chat through the running server. Those deployment receipts are outstanding, so the draft remains held. +Configuration is per tenant. Saved keys are masked when you reopen the dialog; enter both keys again when changing any setting. -The current scope excludes MySQL deployment, Elasticsearch/Infinity knowledge-base retrieval, embedded chatbots, agentic reasoning, agent canvases and hosted Future AGI. SQLite service tests and mocked settings responses do not establish those paths. Stock-image support additionally requires an upstream distribution that contains the exporter. +### Choose what to capture + +Content capture is **on by default**: questions, answers, model prompts and retrieved text can be sent to Future AGI. Enable **Redact content** before sending sensitive data. Redaction keeps identifiers, retrieval scores, model names, token counts, status and timing while removing the text content. + +RAGFlow stores these credentials in **plaintext database columns**. Restrict database access and protect its backups; masked fields in the settings dialog do not encrypt stored credentials. + +## Send a chat and inspect its trace + +Open a RAGFlow chat connected to a dataset with an ingested document, and ask a question answered by that document. Then open **Observe** in Future AGI and select the project name you saved. + +Expand the chat trace: + +- **`ragflow.chat`** — the chat turn and its result. +- **`ragflow.retrieval`** — retrieved text, document identifiers and similarity scores when the turn performs retrieval. +- **`ragflow.llm`** — the model call, messages, answer and token counts. + +Token counts are RAGFlow's tokenizer estimates, not provider billing totals. This setup traces the Go chat pipeline; it does not add tracing to agent canvases. + +## Troubleshooting + +### The Future AGI card is missing + +Check the deployed application image. Stock RAGFlow does not contain the card or exporter; use the Future AGI-enabled build above. An SDK installation alone cannot enable it. + +### Saving the configuration fails + +Check the API key/secret key pair and the collector origin. The RAGFlow server must be able to reach the collector over the network. Re-enter both keys rather than copying the masked values from a previous save. + +### Chats work but traces are missing + +Check the Observe project name and the collector connection, then send a new chat. Export is asynchronous: an unreachable collector or a full queue can drop traces without interrupting chat. A hard shutdown can also lose queued traces; this exporter is not a durable audit log. From 581f77b941df4e229691fc32c1e8564e53f9bd9a Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Mon, 9 Nov 2026 06:54:10 -0800 Subject: [PATCH 7/9] docs(ragflow): pin upstream contribution and document collector policy Link upstream review, replace the obsolete rc1 build with the hardened current-main contribution, and align settings and privacy guidance. Fetch the v1.0.0 tag from upstream because the fork does not publish it. Co-Authored-By: Claude Code --- scripts/integrations.regression.cjs | 12 +++- scripts/ragflow-page.test.mjs | 59 +++++++++++++++---- .../docs/integrations/no-code/ragflow.mdx | 52 ++++++++++------ 3 files changed, 92 insertions(+), 31 deletions(-) diff --git a/scripts/integrations.regression.cjs b/scripts/integrations.regression.cjs index 7c39201e3..6450249a1 100644 --- a/scripts/integrations.regression.cjs +++ b/scripts/integrations.regression.cjs @@ -229,13 +229,21 @@ function luminance(rgb) { return rgb.map(v => v / 255).map(v => v <= 0.04045 ? v assert.equal((await page.locator('h1').innerText()).trim(), 'RAGFlow'); const text = await page.locator('body').innerText(); assert.ok(text.includes('Configure trace export')); - assert.ok(text.includes('User settings → API')); + assert.ok(text.includes('avatar menu → API')); + assert.ok(text.includes('Upstream status:')); + assert.ok(text.includes('under review')); + assert.equal(await page.locator('blockquote a[href="https://github.com/infiniflow/ragflow/pull/22183"]').count(), 1); + assert.ok(text.includes('ALLOW_ANY_HOST=true')); + assert.ok(text.includes('deployment-wide')); + assert.ok(text.includes('Provider error bodies are never exported')); assert.ok(text.includes('plaintext database columns')); assert.ok(text.includes('ragflow.retrieval')); assert.doesNotMatch(text, /Verified development scope|fork-only prototype|Required before an installation guide/i); const build = page.locator('pre').filter({ hasText: 'docker buildx build' }); assert.equal(await build.count(), 1); - assert.ok((await build.innerText()).includes('60492deba70ea7431e13c23de271ab10c3aa0aea')); + assert.ok((await build.innerText()).includes('9b2bcb1d1864c75e35ed7d06d3e750725547290e')); + assert.ok((await build.innerText()).includes('tag v1.0.0')); + assert.ok(text.includes('Infinity v0.7.5')); assert.equal(await page.locator('table').count(), 1); await page.screenshot({ path: path.join(OUT, 'ragflow-customer-guide.png'), fullPage: true }); return { pathname: new URL(page.url()).pathname, settingsTable: true, pinnedBuild: true }; diff --git a/scripts/ragflow-page.test.mjs b/scripts/ragflow-page.test.mjs index 3e3763d9c..e929fe89b 100644 --- a/scripts/ragflow-page.test.mjs +++ b/scripts/ragflow-page.test.mjs @@ -4,32 +4,69 @@ import { readFileSync } from 'node:fs'; import { integrations } from '../src/lib/integrations.mjs'; const page = readFileSync(new URL('../src/pages/docs/integrations/no-code/ragflow.mdx', import.meta.url), 'utf8'); -const source = '60492deba70ea7431e13c23de271ab10c3aa0aea'; +const source = '9b2bcb1d1864c75e35ed7d06d3e750725547290e'; +const upstream = 'https://github.com/infiniflow/ragflow/pull/22183'; -test('RAGFlow guide scopes onboarding to the pinned fork, not a stock image', () => { +test('RAGFlow guide makes the upstream review and interim build status prominent', () => { + assert.ok(page.includes(`[infiniflow/ragflow#22183](${upstream})`)); + assert.ok(page.indexOf(upstream) < page.indexOf('## Prerequisites')); + assert.match(page, /under review/); + assert.match(page, /Until it is merged and released, use the Future AGI-enabled build below/); + assert.match(page, /If the contribution ships in a RAGFlow release, stock images of that release will include/); assert.match(page, /Stock RAGFlow \*\*v1\.0\.0\*\* images do not include this exporter/); - assert.ok(page.includes(`checkout --detach ${source}`)); - assert.ok(page.includes(`fetch --depth 200 origin ${source} tag v1.0.0-rc1`)); - assert.match(page, /docker buildx build --load --network host --target production/); +}); + +test('RAGFlow guide pins the hardened fork and its matching deployment dependencies', () => { + const blocks = [...page.matchAll(/```bash\n([\s\S]*?)\n```/g)]; + assert.equal(blocks.length, 1); + const build = blocks[0][1]; + assert.ok(build.includes(`fetch --depth 200 origin ${source}\n`)); + assert.ok(build.includes('fetch --depth 200 https://github.com/infiniflow/ragflow.git tag v1.0.0\n')); + assert.ok(build.includes(`checkout --detach ${source}`)); + assert.ok(build.includes('docker buildx build --load --network host --build-arg GOPROXY=https://proxy.golang.org,direct --target production --tag ragflow-futureagi:9b2bcb1d --file ragflow-futureagi/Dockerfile ragflow-futureagi')); + assert.ok(page.includes('https://github.com/future-agi/ragflow/tree/contrib/futureagi-tracing')); + assert.ok(page.includes(`https://github.com/future-agi/ragflow/tree/${source}/docker`)); + assert.match(page, /RAGFLOW_IMAGE=ragflow-futureagi:9b2bcb1d/); + assert.match(page, /DOC_ENGINE=infinity/); + assert.match(page, /infiniflow\/infinity:v0\.7\.5-x64-v3/); assert.match(page, /Linux x86-64/); assert.match(page, /MySQL, Infinity, MinIO, Kvrocks and NATS/); - assert.match(page, /separate deployment and database/); + assert.match(page, /separate deployment and database before migrating/); + assert.match(page, /Do not downgrade a database migrated by a newer build/); assert.match(page, /Do not disable the database version guard/); - assert.doesNotMatch(page, /pip install|npx .*traceai|copy.*(?:bridge|exporter class)/i); + assert.doesNotMatch(page, /60492deb|v1\.0\.0-rc1|v0\.7\.3|pip install|npx .*traceai|copy.*(?:bridge|exporter class)/i); const entry = integrations.find(item => item.id === 'ragflow'); assert.equal(entry?.method, 'RAGFlow settings'); assert.match(entry?.summary ?? '', /fork/); }); -test('RAGFlow guide uses the native settings flow and preserves privacy constraints', () => { - for (const text of ['User settings → API', '**Configuration**', '**API key**', '**Secret key**', '**Observe project**', '**Endpoint**', '**Redact content**', '**Save**']) { +test('RAGFlow guide uses the current native settings and saved-key editing flow', () => { + for (const text of ['avatar menu → API', '**Configuration**', '**API key**', '**SECRET KEY**', '**Observe project**', '**Endpoint**', '**Redact content**', '**Save**']) { assert.ok(page.includes(text), text); } - assert.match(page, /https:\/\/api\.futureagi\.com/); + assert.match(page, /Leave blank for `https:\/\/api\.futureagi\.com`/); assert.match(page, /\/tracer\/v1\/traces/); + assert.match(page, /Saved keys are masked/); + assert.match(page, /Leave the key fields blank to keep the saved keys/); + assert.match(page, /enter both keys again when changing the endpoint/); + assert.doesNotMatch(page, /enter both keys again when changing any setting/); +}); + +test('RAGFlow guide preserves the collector host policy and content privacy constraints', () => { + assert.match(page, /Private, loopback and link-local collector addresses are \*\*blocked by default\*\*/); + assert.match(page, /both when saving settings and on every export/); + assert.match(page, /operator must set `ALLOW_ANY_HOST=true` in the RAGFlow server container's environment/); + assert.match(page, /--force-recreate ragflow-cpu/); + assert.match(page, /\*\*deployment-wide\*\*/); + assert.match(page, /not a tenant setting or a collector-specific allowlist/); + assert.match(page, /other guarded outbound integrations/); + assert.match(page, /rejects redirects and does not use environment HTTP proxies/); + assert.match(page, /Future AGI Cloud does not require this opt-in/); assert.match(page, /on by default/); + assert.match(page, /Enable \*\*Redact content\*\* before sending sensitive data/); + assert.match(page, /Provider error bodies are \*\*never exported\*\*, even with content capture on/); + assert.match(page, /fixed failure message/); assert.match(page, /plaintext database columns/); - assert.match(page, /enter both keys again/); assert.match(page, /not provider billing totals/); assert.match(page, /not a durable audit log/); for (const span of ['ragflow.chat', 'ragflow.retrieval', 'ragflow.llm']) assert.ok(page.includes(span)); diff --git a/src/pages/docs/integrations/no-code/ragflow.mdx b/src/pages/docs/integrations/no-code/ragflow.mdx index 459c671c3..becb48acc 100644 --- a/src/pages/docs/integrations/no-code/ragflow.mdx +++ b/src/pages/docs/integrations/no-code/ragflow.mdx @@ -5,9 +5,12 @@ description: "Configure Future AGI trace export in a self-hosted, Future AGI-ena Send RAGFlow chat turns, retrieved documents and model calls to Future AGI Observe from RAGFlow's settings. You do not need to add instrumentation code to your chats. +> **Upstream status:** We have proposed Future AGI tracing in [infiniflow/ragflow#22183](https://github.com/infiniflow/ragflow/pull/22183), which is under review. Until it is merged and released, use the Future AGI-enabled build below. If the contribution ships in a RAGFlow release, stock images of that release will include the **Future AGI** settings card. + ## Prerequisites -- A Linux x86-64 self-hosted deployment of the [Future AGI RAGFlow fork](https://github.com/future-agi/ragflow/tree/60492deba70ea7431e13c23de271ab10c3aa0aea), using the Go backend, MySQL, Infinity, MinIO, Kvrocks and NATS. +- A Linux x86-64 self-hosted deployment using RAGFlow's Go backend, MySQL, Infinity, MinIO, Kvrocks and NATS. +- Docker with Buildx to build the application image below, and Docker Compose for the deployment. - A chat model and an embedding model configured in RAGFlow, with your own provider credentials. - Your Future AGI API key and secret key, available in **Settings → API keys**, and an Observe project name. @@ -15,43 +18,56 @@ Stock RAGFlow **v1.0.0** images do not include this exporter. Installing a trace ### Build the Future AGI-enabled image -If your deployment does not already use the fork, build this pinned image with Docker Buildx: +Build this pinned commit from the Future AGI fork's [contrib/futureagi-tracing branch](https://github.com/future-agi/ragflow/tree/contrib/futureagi-tracing). It is based on upstream development after v1.0.0: ```bash git init ragflow-futureagi git -C ragflow-futureagi remote add origin https://github.com/future-agi/ragflow.git -git -C ragflow-futureagi fetch --depth 200 origin 60492deba70ea7431e13c23de271ab10c3aa0aea tag v1.0.0-rc1 -git -C ragflow-futureagi checkout --detach 60492deba70ea7431e13c23de271ab10c3aa0aea -docker buildx build --load --network host --target production --tag ragflow-futureagi:60492deb --file ragflow-futureagi/Dockerfile ragflow-futureagi +git -C ragflow-futureagi fetch --depth 200 origin 9b2bcb1d1864c75e35ed7d06d3e750725547290e +git -C ragflow-futureagi fetch --depth 200 https://github.com/infiniflow/ragflow.git tag v1.0.0 +git -C ragflow-futureagi checkout --detach 9b2bcb1d1864c75e35ed7d06d3e750725547290e +docker buildx build --load --network host --build-arg GOPROXY=https://proxy.golang.org,direct --target production --tag ragflow-futureagi:9b2bcb1d --file ragflow-futureagi/Dockerfile ragflow-futureagi ``` -Use `ragflow-futureagi:60492deb` as the application image in your self-hosted RAGFlow deployment. Keep its database, document engine, storage, cache and queue services configured using the fork's [deployment configuration](https://github.com/future-agi/ragflow/tree/60492deba70ea7431e13c23de271ab10c3aa0aea/docker). This image runs the Go services and applies database migrations before starting them. +Use the pinned checkout's [deployment configuration](https://github.com/future-agi/ragflow/tree/9b2bcb1d1864c75e35ed7d06d3e750725547290e/docker), not configuration from an older release: + +1. In `ragflow-futureagi/docker/.env`, set `RAGFLOW_IMAGE=ragflow-futureagi:9b2bcb1d` and `DOC_ENGINE=infinity`. Keep the matching dependency versions: this checkout uses **Infinity v0.7.5** (`infiniflow/infinity:v0.7.5-x64-v3`). +2. Set deployment-specific service passwords, including `ADMIN_DEFAULT_PASSWORD`, before first startup. Restrict the Admin port to trusted administrators. +3. Start the services with `docker compose -f ragflow-futureagi/docker/docker-compose.yml up -d`. Keep this checkout pinned; do not follow a release-checkout step that replaces it with stock v1.0.0. -Use a separate deployment and database for this pinned build; do not replace a newer RAGFlow installation or downgrade its database. Keep the release tag and Git history when building so the image's version can be compared with the database version. Do not disable the database version guard to make a mismatched deployment start. +The image applies database migrations before starting the Go services. Evaluate this unreleased build in a separate deployment and database before migrating an existing installation, and back up its metadata and document stores. Do not downgrade a database migrated by a newer build. Keep the release tag and Git history when building so the image's version can be compared with the database version. Do not disable the database version guard to make a mismatched deployment start. ## Configure trace export -1. In RAGFlow, open **User settings → API**. +1. In RAGFlow, open your **avatar menu → API** and scroll to **Future AGI**. 2. On the **Future AGI** card, select **Configuration**. 3. Fill in the following fields: | Field | Value | | --- | --- | | **API key** | Your Future AGI API key | - | **Secret key** | The matching Future AGI secret key | + | **SECRET KEY** | The matching Future AGI secret key | | **Observe project** | The project name to use for these traces | - | **Endpoint** | `https://api.futureagi.com` for Future AGI Cloud, or your self-hosted collector origin | - | **Redact content** | Enable to omit question, answer, prompt and retrieved text | + | **Endpoint** | Leave blank for `https://api.futureagi.com`, or enter your self-hosted collector origin | + | **Redact content** | Enable to omit question, answer, prompt and retrieved text, document names and web URLs | 4. Select **Save**. RAGFlow checks the collector connection and credentials before saving. -Enter the collector origin in **Endpoint**, not a Langfuse URL. RAGFlow sends OTLP/HTTP to `/tracer/v1/traces` and manages the authentication headers itself. The Future AGI and Langfuse configurations are independent. +Enter a collector endpoint you trust, not a Langfuse URL. RAGFlow sends OTLP/HTTP to `/tracer/v1/traces` and manages the authentication headers itself. The Future AGI and Langfuse configurations are independent. Use HTTPS outside a trusted local network; the exporter rejects redirects and does not use environment HTTP proxies. + +Configuration is per tenant. Saved keys are masked when you reopen the dialog. Leave the key fields blank to keep the saved keys when editing the project or redaction setting; enter both keys again when changing the endpoint. -Configuration is per tenant. Saved keys are masked when you reopen the dialog; enter both keys again when changing any setting. +### Use a private collector + +Private, loopback and link-local collector addresses are **blocked by default**, both when saving settings and on every export. For a private collector, the operator must set `ALLOW_ANY_HOST=true` in the RAGFlow server container's environment and recreate the container. With the Compose deployment above, add it to `ragflow-futureagi/docker/.env` and run `docker compose -f ragflow-futureagi/docker/docker-compose.yml up -d --force-recreate ragflow-cpu`. + +This is a **deployment-wide** opt-in that also relaxes the shared host policy for other guarded outbound integrations. It is not a tenant setting or a collector-specific allowlist. Enable it only when your deployment's network and egress controls permit those destinations. Future AGI Cloud does not require this opt-in. A loopback address refers to the RAGFlow container itself, not the Docker host. ### Choose what to capture -Content capture is **on by default**: questions, answers, model prompts and retrieved text can be sent to Future AGI. Enable **Redact content** before sending sensitive data. Redaction keeps identifiers, retrieval scores, model names, token counts, status and timing while removing the text content. +Content capture is **on by default**: questions, answers, model prompts, retrieved text, document names and web URLs can be sent to Future AGI. Enable **Redact content** before sending sensitive data. Redaction keeps identifiers, retrieval scores, model names, token counts, status and timing while removing those content fields. + +Provider error bodies are **never exported**, even with content capture on. Failed turns use a fixed failure message instead of provider error details, which can contain credentials. RAGFlow stores these credentials in **plaintext database columns**. Restrict database access and protect its backups; masked fields in the settings dialog do not encrypt stored credentials. @@ -65,18 +81,18 @@ Expand the chat trace: - **`ragflow.retrieval`** — retrieved text, document identifiers and similarity scores when the turn performs retrieval. - **`ragflow.llm`** — the model call, messages, answer and token counts. -Token counts are RAGFlow's tokenizer estimates, not provider billing totals. This setup traces the Go chat pipeline; it does not add tracing to agent canvases. +Token counts are RAGFlow's tokenizer estimates, not provider billing totals. This setup traces the Go chat pipeline, including streaming. Agentic chat has a turn-level trace; internal agent tools, individual reasoning calls, ingestion and standalone retrieval are not instrumented. ## Troubleshooting ### The Future AGI card is missing -Check the deployed application image. Stock RAGFlow does not contain the card or exporter; use the Future AGI-enabled build above. An SDK installation alone cannot enable it. +Check the deployed application image and the upstream status above. Use the Future AGI-enabled build until a RAGFlow release includes the contribution. An SDK installation alone cannot enable it. ### Saving the configuration fails -Check the API key/secret key pair and the collector origin. The RAGFlow server must be able to reach the collector over the network. Re-enter both keys rather than copying the masked values from a previous save. +Check the API key/secret key pair and the collector origin. The RAGFlow server must be able to reach the collector over the network, and private destinations require the operator opt-in above. When changing the endpoint, re-enter both keys rather than copying the masked values from a previous save. ### Chats work but traces are missing -Check the Observe project name and the collector connection, then send a new chat. Export is asynchronous: an unreachable collector or a full queue can drop traces without interrupting chat. A hard shutdown can also lose queued traces; this exporter is not a durable audit log. +Check the Observe project name and the collector connection, then send a new chat. Export is asynchronous: an unreachable collector or a full queue can drop traces without interrupting chat. Shutdown attempts a bounded flush, but a hard shutdown can lose queued traces; this exporter is not a durable audit log. From 0a53a3b15a3b6ee654998abc1e4d728f0a22095a Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Mon, 9 Nov 2026 07:12:24 -0800 Subject: [PATCH 8/9] docs(ragflow): use public npm for reproducible reader builds The upstream npm mirror returned repeated HTTP 500 tarball responses in the exact-reader E2B build. Change only registry URLs in the checkout, preserving package versions, integrity hashes and the Dockerfile. Co-Authored-By: Claude Code --- scripts/integrations.regression.cjs | 1 + scripts/ragflow-page.test.mjs | 2 ++ src/pages/docs/integrations/no-code/ragflow.mdx | 3 ++- 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/scripts/integrations.regression.cjs b/scripts/integrations.regression.cjs index 6450249a1..e89660033 100644 --- a/scripts/integrations.regression.cjs +++ b/scripts/integrations.regression.cjs @@ -243,6 +243,7 @@ function luminance(rgb) { return rgb.map(v => v / 255).map(v => v <= 0.04045 ? v assert.equal(await build.count(), 1); assert.ok((await build.innerText()).includes('9b2bcb1d1864c75e35ed7d06d3e750725547290e')); assert.ok((await build.innerText()).includes('tag v1.0.0')); + assert.ok((await build.innerText()).includes('https://registry.npmjs.org')); assert.ok(text.includes('Infinity v0.7.5')); assert.equal(await page.locator('table').count(), 1); await page.screenshot({ path: path.join(OUT, 'ragflow-customer-guide.png'), fullPage: true }); diff --git a/scripts/ragflow-page.test.mjs b/scripts/ragflow-page.test.mjs index e929fe89b..b1e820809 100644 --- a/scripts/ragflow-page.test.mjs +++ b/scripts/ragflow-page.test.mjs @@ -23,6 +23,8 @@ test('RAGFlow guide pins the hardened fork and its matching deployment dependenc assert.ok(build.includes(`fetch --depth 200 origin ${source}\n`)); assert.ok(build.includes('fetch --depth 200 https://github.com/infiniflow/ragflow.git tag v1.0.0\n')); assert.ok(build.includes(`checkout --detach ${source}`)); + assert.ok(build.includes("sed -i 's#https://registry\\.npmmirror\\.com#https://registry.npmjs.org#g' ragflow-futureagi/web/.npmrc ragflow-futureagi/web/package-lock.json")); + assert.match(page, /without changing locked package versions or integrity hashes/); assert.ok(build.includes('docker buildx build --load --network host --build-arg GOPROXY=https://proxy.golang.org,direct --target production --tag ragflow-futureagi:9b2bcb1d --file ragflow-futureagi/Dockerfile ragflow-futureagi')); assert.ok(page.includes('https://github.com/future-agi/ragflow/tree/contrib/futureagi-tracing')); assert.ok(page.includes(`https://github.com/future-agi/ragflow/tree/${source}/docker`)); diff --git a/src/pages/docs/integrations/no-code/ragflow.mdx b/src/pages/docs/integrations/no-code/ragflow.mdx index becb48acc..d528eb6c8 100644 --- a/src/pages/docs/integrations/no-code/ragflow.mdx +++ b/src/pages/docs/integrations/no-code/ragflow.mdx @@ -18,7 +18,7 @@ Stock RAGFlow **v1.0.0** images do not include this exporter. Installing a trace ### Build the Future AGI-enabled image -Build this pinned commit from the Future AGI fork's [contrib/futureagi-tracing branch](https://github.com/future-agi/ragflow/tree/contrib/futureagi-tracing). It is based on upstream development after v1.0.0: +Build this pinned commit from the Future AGI fork's [contrib/futureagi-tracing branch](https://github.com/future-agi/ragflow/tree/contrib/futureagi-tracing). It is based on upstream development after v1.0.0. The commands use the public npm registry instead of the checkout's npm mirror, without changing locked package versions or integrity hashes: ```bash git init ragflow-futureagi @@ -26,6 +26,7 @@ git -C ragflow-futureagi remote add origin https://github.com/future-agi/ragflow git -C ragflow-futureagi fetch --depth 200 origin 9b2bcb1d1864c75e35ed7d06d3e750725547290e git -C ragflow-futureagi fetch --depth 200 https://github.com/infiniflow/ragflow.git tag v1.0.0 git -C ragflow-futureagi checkout --detach 9b2bcb1d1864c75e35ed7d06d3e750725547290e +sed -i 's#https://registry\.npmmirror\.com#https://registry.npmjs.org#g' ragflow-futureagi/web/.npmrc ragflow-futureagi/web/package-lock.json docker buildx build --load --network host --build-arg GOPROXY=https://proxy.golang.org,direct --target production --tag ragflow-futureagi:9b2bcb1d --file ragflow-futureagi/Dockerfile ragflow-futureagi ``` From 00d3e85246abbf2c023233b2dec96eef2222c382 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Mon, 9 Nov 2026 07:27:00 -0800 Subject: [PATCH 9/9] docs(ragflow): sequence builder targets to reduce peak memory Build the unchanged Go and web stages one after another before the production target, matching the resource-safe qualified build sequence. Co-Authored-By: Claude Code --- scripts/integrations.regression.cjs | 3 +++ scripts/ragflow-page.test.mjs | 3 +++ src/pages/docs/integrations/no-code/ragflow.mdx | 4 +++- 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/scripts/integrations.regression.cjs b/scripts/integrations.regression.cjs index e89660033..2b641a2c1 100644 --- a/scripts/integrations.regression.cjs +++ b/scripts/integrations.regression.cjs @@ -244,6 +244,9 @@ function luminance(rgb) { return rgb.map(v => v / 255).map(v => v <= 0.04045 ? v assert.ok((await build.innerText()).includes('9b2bcb1d1864c75e35ed7d06d3e750725547290e')); assert.ok((await build.innerText()).includes('tag v1.0.0')); assert.ok((await build.innerText()).includes('https://registry.npmjs.org')); + for (const target of ['go-builder', 'web-builder', 'production']) { + assert.ok((await build.innerText()).includes(`--target ${target}`)); + } assert.ok(text.includes('Infinity v0.7.5')); assert.equal(await page.locator('table').count(), 1); await page.screenshot({ path: path.join(OUT, 'ragflow-customer-guide.png'), fullPage: true }); diff --git a/scripts/ragflow-page.test.mjs b/scripts/ragflow-page.test.mjs index b1e820809..c198e5dec 100644 --- a/scripts/ragflow-page.test.mjs +++ b/scripts/ragflow-page.test.mjs @@ -25,6 +25,9 @@ test('RAGFlow guide pins the hardened fork and its matching deployment dependenc assert.ok(build.includes(`checkout --detach ${source}`)); assert.ok(build.includes("sed -i 's#https://registry\\.npmmirror\\.com#https://registry.npmjs.org#g' ragflow-futureagi/web/.npmrc ragflow-futureagi/web/package-lock.json")); assert.match(page, /without changing locked package versions or integrity hashes/); + const targets = [...build.matchAll(/--target (\S+)/g)].map(match => match[1]); + assert.deepEqual(targets, ['go-builder', 'web-builder', 'production']); + assert.match(page, /Build the Go and web targets in sequence to reduce peak memory use/); assert.ok(build.includes('docker buildx build --load --network host --build-arg GOPROXY=https://proxy.golang.org,direct --target production --tag ragflow-futureagi:9b2bcb1d --file ragflow-futureagi/Dockerfile ragflow-futureagi')); assert.ok(page.includes('https://github.com/future-agi/ragflow/tree/contrib/futureagi-tracing')); assert.ok(page.includes(`https://github.com/future-agi/ragflow/tree/${source}/docker`)); diff --git a/src/pages/docs/integrations/no-code/ragflow.mdx b/src/pages/docs/integrations/no-code/ragflow.mdx index d528eb6c8..460cecbeb 100644 --- a/src/pages/docs/integrations/no-code/ragflow.mdx +++ b/src/pages/docs/integrations/no-code/ragflow.mdx @@ -18,7 +18,7 @@ Stock RAGFlow **v1.0.0** images do not include this exporter. Installing a trace ### Build the Future AGI-enabled image -Build this pinned commit from the Future AGI fork's [contrib/futureagi-tracing branch](https://github.com/future-agi/ragflow/tree/contrib/futureagi-tracing). It is based on upstream development after v1.0.0. The commands use the public npm registry instead of the checkout's npm mirror, without changing locked package versions or integrity hashes: +Build this pinned commit from the Future AGI fork's [contrib/futureagi-tracing branch](https://github.com/future-agi/ragflow/tree/contrib/futureagi-tracing). It is based on upstream development after v1.0.0. The commands use the public npm registry instead of the checkout's npm mirror, without changing locked package versions or integrity hashes. Build the Go and web targets in sequence to reduce peak memory use, then assemble the production image: ```bash git init ragflow-futureagi @@ -27,6 +27,8 @@ git -C ragflow-futureagi fetch --depth 200 origin 9b2bcb1d1864c75e35ed7d06d3e750 git -C ragflow-futureagi fetch --depth 200 https://github.com/infiniflow/ragflow.git tag v1.0.0 git -C ragflow-futureagi checkout --detach 9b2bcb1d1864c75e35ed7d06d3e750725547290e sed -i 's#https://registry\.npmmirror\.com#https://registry.npmjs.org#g' ragflow-futureagi/web/.npmrc ragflow-futureagi/web/package-lock.json +docker buildx build --network host --build-arg GOPROXY=https://proxy.golang.org,direct --target go-builder --file ragflow-futureagi/Dockerfile ragflow-futureagi +docker buildx build --network host --target web-builder --file ragflow-futureagi/Dockerfile ragflow-futureagi docker buildx build --load --network host --build-arg GOPROXY=https://proxy.golang.org,direct --target production --tag ragflow-futureagi:9b2bcb1d --file ragflow-futureagi/Dockerfile ragflow-futureagi ```