Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

chore: agfs-client默认切到binding-client模式 (#430)

chuanbao666c1537a5dc5e6
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index aab836b3c..3c3ef541d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,7 +51,7 @@ source .venv/bin/activate # Linux/macOS
#### Local Development & AGFS Compilation
-If you modify the **AGFS (Go)** code or **C++ extensions**, you need to re-compile and re-install them to make the changes take effect in your environment. Run the following command in the project root:
+OpenViking defaults to `binding-client` mode for AGFS, which requires a pre-built shared library. If you modify the **AGFS (Go)** code or **C++ extensions**, or if the pre-built library is not found, you need to re-compile and re-install them. Run the following command in the project root:
```bash
uv pip install -e . --force-reinstall
diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md
index 244f79c96..ff5854671 100644
--- a/CONTRIBUTING_CN.md
+++ b/CONTRIBUTING_CN.md
@@ -51,7 +51,7 @@ source .venv/bin/activate # Linux/macOS
#### 本地开发与 AGFS 编译
-如果你修改了 **AGFS (Go)** 代码或 **C++ 扩展**,你需要重新编译并安装它们,以使更改在本地环境中生效。在项目根目录下运行以下命令:
+OpenViking 默认使用 `binding-client` 模式,这需要一个预先构建的共享库。如果你修改了 **AGFS (Go)** 代码或 **C++ 扩展**,或者预编译库未找到,你需要重新编译并安装它们,以使更改在本地环境中生效。在项目根目录下运行以下命令:
```bash
uv pip install -e . --force-reinstall
diff --git a/README.md b/README.md
index a479fe18c..04e975cc2 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,8 @@ With OpenViking, developers can build an Agent's brain just like managing local
Before starting with OpenViking, please ensure your environment meets the following requirements:
- **Python Version**: 3.10 or higher
+- **Go Version**: 1.19 or higher (Required for building AGFS components)
+- **C++ Compiler**: GCC 9+ or Clang 11+ (Required for building core extensions)
- **Operating System**: Linux, macOS, Windows
- **Network Connection**: A stable network connection is required (for downloading dependencies and accessing model services)
diff --git a/README_CN.md b/README_CN.md
index e51849473..8ac5f417a 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -59,6 +59,8 @@
在开始使用 OpenViking 之前,请确保您的环境满足以下要求:
- **Python 版本**:3.10 或更高版本
+- **Go 版本**:1.19 或更高(从源码构建 AGFS 组件需要)
+- **C++ 编译器**:GCC 9+ 或 Clang 11+(构建核心扩展需要,必须支持 C++17)
- **操作系统**:Linux、macOS、Windows
- **网络连接**:需要稳定的网络连接(用于下载依赖和访问模型服务)
diff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.md
index 32b0fe70a..4992480e8 100644
--- a/docs/en/faq/faq.md
+++ b/docs/en/faq/faq.md
@@ -56,11 +56,25 @@ viking://
### What are the environment requirements?
- **Python Version**: 3.10 or higher
+- **Build Tools** (if installing from source or on unsupported platforms): Go 1.19+, GCC 9+ or Clang 11+
- **Required Dependencies**: Embedding model (Volcengine Doubao recommended)
- **Optional Dependencies**:
- VLM (Vision Language Model): For multimodal content processing and semantic extraction
- Rerank model: For improved retrieval precision
+### What are `binding-client` and `http-client`? Which one should I choose?
+
+- **`binding-client` (Default)**: Runs AGFS logic directly within the Python process via CGO bindings. Advantages: extremely high performance, zero network latency; Disadvantages: requires a compiled AGFS shared library locally.
+- **`http-client`**: Communicates with a standalone `agfs-server` via HTTP. Advantages: decoupled deployment, no local Go compilation needed; Disadvantages: some network communication overhead.
+
+If your environment supports Go compilation or you've installed a Wheel package containing pre-compiled libraries, the default `binding-client` is recommended.
+
+### What should I do if I encounter "AGFS binding library not found"?
+
+This usually means the AGFS shared library is not pre-built in your environment. You can:
+1. **Re-compile and install**: Run `pip install -e . --force-reinstall` in the project root (requires Go environment).
+2. **Switch to HTTP mode**: Set `storage.agfs.mode = "http-client"` in your `ov.conf` and ensure an `agfs-server` is running.
+
### How do I install/upgrade OpenViking?
```bash
diff --git a/docs/zh/faq/faq.md b/docs/zh/faq/faq.md
index 8e72b7705..680300058 100644
--- a/docs/zh/faq/faq.md
+++ b/docs/zh/faq/faq.md
@@ -56,11 +56,25 @@ viking://
### 环境要求是什么?
- **Python 版本**:3.10 或更高
+- **编译工具**(如果从源码安装或在不支持的平台上):Go 1.19+, GCC 9+ 或 Clang 11+
- **必需依赖**:Embedding 模型(推荐火山引擎 Doubao)
- **可选依赖**:
- VLM(视觉语言模型):用于多模态内容处理和语义提取
- Rerank 模型:用于提升检索精度
+### 什么是 `binding-client` 和 `http-client`?我该选哪个?
+
+- **`binding-client`(默认值)**:通过 CGO 绑定直接在 Python 进程内运行 AGFS 逻辑。优点是性能极高,无网络延迟;缺点是需要本地有编译好的 AGFS 共享库。
+- **`http-client`**:通过 HTTP 协议与独立的 `agfs-server` 通信。优点是部署解耦,不需要本地编译 Go 代码;缺点是有一定的网络通信开销。
+
+如果你的环境支持编译 Go 代码,或者安装了包含预编译库的 Wheel 包,推荐使用默认的 `binding-client`。
+
+### 遇到 "AGFS binding library not found" 错误怎么办?
+
+这通常是因为本地没有编译好的 AGFS 共享库。你可以:
+1. **重新编译安装**:在项目根目录运行 `pip install -e . --force-reinstall`(需要 Go 环境)。
+2. **切换到 HTTP 模式**:在 `ov.conf` 中设置 `storage.agfs.mode = "http-client"`,并确保有一个正在运行的 `agfs-server`。
+
### 如何安装 OpenViking?
```bash
diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.py
index 2f2df7c81..8e3061fef 100644
--- a/openviking_cli/utils/config/agfs_config.py
+++ b/openviking_cli/utils/config/agfs_config.py
@@ -85,7 +85,7 @@ class AGFSConfig(BaseModel):
)
mode: str = Field(
- default="http-client",
+ default="binding-client",
description="AGFS client mode: 'http-client' | 'binding-client'",
)
diff --git a/tests/agfs/test_fs_local.py b/tests/agfs/test_fs_local.py
index 182e5ea67..3a428ed68 100644
--- a/tests/agfs/test_fs_local.py
+++ b/tests/agfs/test_fs_local.py
@@ -15,7 +15,12 @@ from openviking_cli.utils.config.agfs_config import AGFSConfig
# 1. Direct configuration for testing
AGFS_CONF = AGFSConfig(
- path="/tmp/ov-test", backend="local", port=1833, url="http://localhost:1833", timeout=10
+ path="/tmp/ov-test",
+ backend="local",
+ port=1833,
+ mode="http-client",
+ url="http://localhost:1833",
+ timeout=10,
)
# clean up test directory if it exists