From 5d015e48c192e14e27384df13c54e2396e3f87ac Mon Sep 17 00:00:00 2001 From: writinwaters <93570324+writinwaters@users.noreply.github.com> Date: Wed, 3 Sep 2025 14:23:03 +0800 Subject: [PATCH] Docs: Updated the Code component reference (#9884) ### What problem does this PR solve? ### Type of change - [x] Documentation Update --- .../agent/agent_component_reference/code.mdx | 139 ++++++++++++++++++ .../agent_component_reference/retrieval.mdx | 8 +- 2 files changed, 143 insertions(+), 4 deletions(-) diff --git a/docs/guides/agent/agent_component_reference/code.mdx b/docs/guides/agent/agent_component_reference/code.mdx index f7004b5ff..388b7a96c 100644 --- a/docs/guides/agent/agent_component_reference/code.mdx +++ b/docs/guides/agent/agent_component_reference/code.mdx @@ -13,6 +13,32 @@ A component that enables users to integrate Python or JavaScript codes into thei A **Code** component is essential when you need to integrate complex code logic (Python or JavaScript) into your Agent for dynamic data processing. +## Prerequisites + +### 1. Ensure gVisor is properly installed + +We use gVisor to isolate code execution from the host system. Please follow [the official installation guide](https://gvisor.dev/docs/user_guide/install/) to install gVisor, ensuring your operating system is compatible before proceeding. + +### 2. Ensure Sandbox is properly installed + +RAGFlow Sandbox is a secure, pluggable code execution backend. It serves as the code executor for the **Code** component. Please follow the [instructions here](https://github.com/infiniflow/ragflow/tree/main/sandbox) to install RAGFlow Sandbox. + +:::tip NOTE +If your RAGFlow Sandbox is not working, please be sure to consult the [Troubleshooting](#troubleshooting) section in this document. We assure you that it addresses 99.99% of the issues! +::: + +### 3. (Optional) Install necessary dependencies + +If you need to import your own Python or JavaScript packages into Sandbox, please follow the commands provided in the [How to import my own Python or JavaScript packages into Sandbox?](#how-to-import-my-own-python-or-javascript-packages-into-sandbox) section to install the additional dependencies. + +### 4. Enable Sandbox-specific settings in RAGFlow + +Ensure all Sandbox-specific settings are enabled in **ragflow/docker/.env**. + +### 5. Restart the service after making changes + +Any changes to the configuration or environment *require* a full service restart to take effect. + ## Configurations ### Input @@ -55,4 +81,117 @@ You define the output variable(s) of the **Code** component here. The defined output variable(s) will be auto-populated here. +## Troubleshooting +### `HTTPConnectionPool(host='sandbox-executor-manager', port=9385): Read timed out.` + +**Root cause** + +- You did not properly install gVisor and `runsc` was not recognized as a valid Docker runtime. +- You did not pull the required base images for the runners and no runner was started. + +**Solution** + +For the gVisor issue: + +1. Install [gVisor](https://gvisor.dev/docs/user_guide/install/). +2. Restart Docker. +3. Run the following to double check: + + ```bash + docker run --rm --runtime=runsc hello-world + ``` + +For the base image issue, pull the required base images: + +```bash +docker pull infiniflow/sandbox-base-nodejs:latest +docker pull infiniflow/sandbox-base-python:latest +``` + +### `HTTPConnectionPool(host='none', port=9385): Max retries exceeded.` + +**Root cause** + +`sandbox-executor-manager` is not mapped in `/etc/hosts`. + +**Solution** + +Add a new entry to `/etc/hosts`: + +`127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager` + +### `Container pool is busy` + +**Root cause** + +All runners are currently in use, executing tasks. + +**Solution** + +Please try again shortly or increase the pool size in the configuration to improve availability and reduce waiting times. + + +## Frequently asked questions + +### How to import my own Python or JavaScript packages into Sandbox? + +To install the additional dependencies for your Python packages: + +```bash +(ragflow) ➜ ragflow/sandbox main ✓ pwd +``` + +```bash +(ragflow) ➜ ragflow/sandbox main ✓ ls +``` + +```bash +(ragflow) ➜ ragflow/sandbox main ✓ echo "openpyxl" >> sandbox_base_image/python/requirements.txt +``` + +```bash +(ragflow) ➜ ragflow/sandbox main ✗ cat sandbox_base_image/python/requirements.txt +``` + +```bash +(ragflow) ➜ ragflow/sandbox main ✗ make +``` + +```bash +(ragflow) ➜ ragflow/sandbox main ✗ docker exec -it sandbox_python_0 /bin/bash +``` + +To install the additional dependencies for your JavaScript packages: + +```bash +(ragflow) ➜ ragflow/sandbox main ✓ pwd +/home/infiniflow/workspace/ragflow/sandbox + +``` + +```bash +(ragflow) ➜ ragflow/sandbox main ✓ cd sandbox_base_image/nodejs +``` + +```bash +(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✓ npm install lodash +``` + +```bash +(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✗ make +make: *** No targets specified and no makefile found. Stop. +(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✗ lg +(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✓ ls +node_modules Dockerfile package-lock.json package.json +(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✓ cd .. +(ragflow) ➜ ragflow/sandbox/sandbox_base_image main ✓ ls +nodejs python +(ragflow) ➜ ragflow/sandbox/sandbox_base_image main ✓ cd .. +(ragflow) ➜ ragflow/sandbox main ✓ ls +asserts executor_manager sandbox_base_image scripts tests docker-compose.yml Makefile pyproject.toml README.md uv.lock +(ragflow) ➜ ragflow/sandbox main ✓ pwd +/home/infiniflow/workspace/ragflow/sandbox +(ragflow) ➜ ragflow/sandbox main ✓ cd sandbox_base_image/nodejs +(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✓ npm install lodash +``` diff --git a/docs/guides/agent/agent_component_reference/retrieval.mdx b/docs/guides/agent/agent_component_reference/retrieval.mdx index 8bbad4374..0b69c641f 100644 --- a/docs/guides/agent/agent_component_reference/retrieval.mdx +++ b/docs/guides/agent/agent_component_reference/retrieval.mdx @@ -27,7 +27,7 @@ The corresponding configuration panel appears to the right of the canvas. Use th ### 2. Input query variable(s) -The **Retrieval** component relies on query variables to specify its queries. +The **Retrieval** component depends on query variables to specify its queries. :::caution IMPORTANT - If you use the **Retrieval** component as a standalone workflow module, input query variables in the **Input Variables** text box. @@ -42,7 +42,7 @@ You can specify one or multiple knowledge bases to retrieve data from. If select ### 4. Expand **Advanced Settings** to configure the retrieval method -By default, a combination of weighted keyword similarity and weighted vector cosine similarity is used during retrieval. If a rerank model is selected, a combination of weighted keyword similarity and weighted reranking score will be used for retrieval. +By default, a combination of weighted keyword similarity and weighted vector cosine similarity is used for retrieval. If a rerank model is selected, a combination of weighted keyword similarity and weighted reranking score will be used instead. As a starter, you can skip this step to stay with the default retrieval method. @@ -57,9 +57,9 @@ If your user query is different from the languages of the knowledge bases, you c ### 6. Test retrieval results -Click the triangle button on the top of canvas to test the retrieval results. +Click the **Run** button on the top of canvas to test the retrieval results. -### 6. Choose the next component +### 7. Choose the next component When necessary, click the **+** button on the **Retrieval** component to choose the next component in the worflow from the dropdown list.