feat(agfs): agfs新增binding client

.gitignore

@@ -167,6 +167,5 @@ test_db_*/
 test_project_root/
 benchmark_stress_db/
 examples/data/
-third_party/agfs/bin/
 openviking/_version.py
 specs/

README.md

@@ -349,6 +349,23 @@ set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf"
 
 > 💡 **Tip**: You can also place the configuration file in other locations, just specify the correct path in the environment variable.
 
+#### AGFS Binding Mode (High Performance)
+
+For better performance, you can use the Python Binding mode to bypass HTTP overhead by directly calling the AGFS core.
+
+**Update your `ov.conf`**:
+   Add `mode` to the `agfs` section:
+   ```json
+   {
+     "storage": {
+       "agfs": {
+         "mode": "binding-client",
+         "backend": "local"
+       }
+     }
+   }
+   ```
+
 ### 4. Run Your First Example
 
 > 📝 **Prerequisite**: Ensure you have completed the environment configuration in the previous step.

docs/en/guides/01-configuration.md

@@ -321,6 +321,79 @@ Storage backend configuration.
 }
 ```
 
+#### agfs
+
+| Parameter | Type | Description | Default |
+|-----------|------|-------------|---------|
+| `mode` | str | `"http-client"` or `"binding-client"` | `"http-client"` |
+| `backend` | str | `"local"`, `"s3"`, or `"memory"` | `"local"` |
+| `path` | str | Local directory path for `local` backend | `"./data"` |
+| `url` | str | AGFS service URL for `http-client` mode | `"http://localhost:1833"` |
+| `timeout` | float | Request timeout in seconds | `10.0` |
+
+**Configuration Examples**
+
+<details>
+<summary><b>HTTP Client (Default)</b></summary>
+
+Connects to a remote or local AGFS service via HTTP.
+
+```json
+{
+  "storage": {
+    "agfs": {
+      "mode": "http-client",
+      "url": "http://localhost:1833",
+      "timeout": 10.0
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Binding Client (High Performance)</b></summary>
+
+Directly uses the AGFS Go implementation through a shared library. 
+
+**Config**:
+```json
+{
+  "storage": {
+    "agfs": {
+      "mode": "binding-client",
+      "backend": "local",
+      "path": "./data"
+    }
+  }
+}
+```
+
+</details>
+
+**S3 Backend**
+
+```json
+{
+  "storage": {
+    "agfs": {
+      "backend": "s3",
+      "s3": {
+        "bucket": "my-bucket",
+        "endpoint": "s3.amazonaws.com",
+        "region": "us-east-1",
+        "access_key": "your-ak",
+        "secret_key": "your-sk"
+      }
+    }
+  }
+}
+```
+
+#### vectordb
+
+
 ## Config Files
 
 OpenViking uses two config files:

docs/zh/guides/01-configuration.md

@@ -328,6 +328,78 @@ OpenViking 使用 JSON 配置文件（`ov.conf`）进行设置。配置文件支
 }
 ```
 
+#### agfs
+
+| 参数 | 类型 | 说明 | 默认值 |
+|------|------|------|--------|
+| `mode` | str | `"http-client"` 或 `"binding-client"` | `"http-client"` |
+| `backend` | str | `"local"`、`"s3"` 或 `"memory"` | `"local"` |
+| `path` | str | `local` 后端的本地目录路径 | `"./data"` |
+| `url` | str | `http-client` 模式下的 AGFS 服务地址 | `"http://localhost:1833"` |
+| `timeout` | float | 请求超时时间（秒） | `10.0` |
+
+**配置示例**
+
+<details>
+<summary><b>HTTP Client（默认）</b></summary>
+
+通过 HTTP 连接到远程或本地的 AGFS 服务。
+
+```json
+{
+  "storage": {
+    "agfs": {
+      "mode": "http-client",
+      "url": "http://localhost:1833",
+      "timeout": 10.0
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Binding Client（高性能）</b></summary>
+
+通过共享库直接使用 AGFS 的 Go 实现。
+
+**配置**：
+```json
+{
+  "storage": {
+    "agfs": {
+      "mode": "binding-client",
+      "backend": "local",
+      "path": "./data"
+    }
+  }
+}
+```
+
+</details>
+
+**S3 后端**
+
+```json
+{
+  "storage": {
+    "agfs": {
+      "backend": "s3",
+      "s3": {
+        "bucket": "my-bucket",
+        "endpoint": "s3.amazonaws.com",
+        "region": "us-east-1",
+        "access_key": "your-ak",
+        "secret_key": "your-sk"
+      }
+    }
+  }
+}
+```
+
+#### vectordb
+
 ## 配置文件
 
 OpenViking 使用两个配置文件：

openviking/eval/ragas/playback.py

@@ -88,9 +88,7 @@ def to_dict(self) -> Dict[str, Any]:
         )
         agfs_fs_total = self.agfs_fs_success_count + self.agfs_fs_error_count
         agfs_fs_success_rate = (
-            self.agfs_fs_success_count / agfs_fs_total * 100
-            if agfs_fs_total > 0
-            else 0
+            self.agfs_fs_success_count / agfs_fs_total * 100 if agfs_fs_total > 0 else 0
         )
         avg_agfs_calls = (
             self.total_agfs_calls / self.total_viking_fs_operations
@@ -217,29 +215,26 @@ def _init_backends(self) -> None:
         from openviking.agfs_manager import AGFSManager
         from openviking.storage.viking_fs import init_viking_fs
         from openviking.storage.viking_vector_index_backend import VikingVectorIndexBackend
+        from openviking.utils.agfs_utils import create_agfs_client
         from openviking_cli.utils.config import get_openviking_config
         from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig
 
         config = get_openviking_config()
-
-        agfs_url = config.storage.agfs.url
+        agfs_config = config.storage.agfs
         agfs_manager = None
 
-        if config.storage.agfs.backend == "local":
-            agfs_manager = AGFSManager(config=config.storage.agfs)
+        # Determine if we need to start AGFSManager for HTTP mode
+        mode = getattr(agfs_config, "mode", "http-client")
+        if mode == "http-client":
+            agfs_manager = AGFSManager(config=agfs_config)
             agfs_manager.start()
-            agfs_url = agfs_manager.url
-            logger.info(f"[IOPlayback] Started AGFS at {agfs_url}")
-        elif config.storage.agfs.backend in ["s3", "memory"]:
-            agfs_manager = AGFSManager(config=config.storage.agfs)
-            agfs_manager.start()
-            agfs_url = agfs_manager.url
             logger.info(
-                f"[IOPlayback] Started AGFS with {config.storage.agfs.backend} backend at {agfs_url}"
+                f"[IOPlayback] Started AGFS manager in HTTP mode at {agfs_manager.url} "
+                f"with {agfs_config.backend} backend"
             )
-        elif not agfs_url:
-            agfs_url = "http://localhost:8080"
-            logger.warning(f"[IOPlayback] No AGFS URL configured, using default: {agfs_url}")
+
+        # Create AGFS client using utility
+        agfs_client = create_agfs_client(agfs_config)
 
         vector_store = None
         if self.enable_vikingdb:
@@ -255,8 +250,9 @@ def _init_backends(self) -> None:
             vector_store = VikingVectorIndexBackend(config=backend_config)
 
         if self.enable_fs:
+            # Use init_viking_fs which handles mode (HTTP/Binding) automatically based on agfs_config
             self._viking_fs = init_viking_fs(
-                agfs_url=agfs_url,
+                agfs=agfs_client,
                 vector_store=vector_store,
             )
         self._vector_store = vector_store
@@ -332,7 +328,9 @@ def process_arg(arg: Any) -> Any:
 
         return result
 
-    def _compare_agfs_calls(self, recorded_calls: List[Any], actual_calls: List[Dict[str, Any]]) -> bool:
+    def _compare_agfs_calls(
+        self, recorded_calls: List[Any], actual_calls: List[Dict[str, Any]]
+    ) -> bool:
         """
         Compare recorded AGFS calls with actual AGFS calls.
 
@@ -365,14 +363,10 @@ def _compare_agfs_calls(self, recorded_calls: List[Any], actual_calls: List[Dict
                 )
                 return False
             if recorded_req != actual_call["request"]:
-                logger.warning(
-                    f"AGFS request mismatch for operation {recorded_op}"
-                )
+                logger.warning(f"AGFS request mismatch for operation {recorded_op}")
                 return False
             if recorded_success != actual_call["success"]:
-                logger.warning(
-                    f"AGFS success status mismatch for operation {recorded_op}"
-                )
+                logger.warning(f"AGFS success status mismatch for operation {recorded_op}")
                 return False
 
         return True

openviking/server/routers/sessions.py

@@ -7,7 +7,7 @@
 from fastapi import APIRouter, Depends, Path
 from pydantic import BaseModel, model_validator
 
-from openviking.message.part import Part, TextPart, part_from_dict
+from openviking.message.part import TextPart, part_from_dict
 from openviking.server.auth import get_request_context
 from openviking.server.dependencies import get_service
 from openviking.server.identity import RequestContext

openviking/service/core.py

@@ -67,6 +67,7 @@ def __init__(
         # Infrastructure
         self._agfs_manager: Optional[AGFSManager] = None
         self._agfs_url: Optional[str] = None
+        self._agfs_client: Optional[Any] = None
         self._queue_manager: Optional[QueueManager] = None
         self._vikingdb_manager: Optional[VikingDBManager] = None
         self._viking_fs: Optional[VikingFS] = None
@@ -106,24 +107,30 @@ def _init_storage(
         max_concurrent_semantic: int = 100,
     ) -> None:
         """Initialize storage resources."""
-        if config.agfs.backend == "local":
+        from openviking.utils.agfs_utils import create_agfs_client
+
+        mode = getattr(config.agfs, "mode", "http-client")
+        if mode == "http-client" and config.agfs.backend == "local":
             self._agfs_manager = AGFSManager(config=config.agfs)
             self._agfs_manager.start()
             self._agfs_url = self._agfs_manager.url
             config.agfs.url = self._agfs_url
         else:
             self._agfs_url = config.agfs.url
 
-        # Initialize QueueManager
-        if self._agfs_url:
+        # Create AGFS client using utility
+        self._agfs_client = create_agfs_client(config.agfs)
+
+        # Initialize QueueManager with agfs_client
+        if self._agfs_client:
             self._queue_manager = init_queue_manager(
-                agfs_url=self._agfs_url,
+                agfs=self._agfs_client,
                 timeout=config.agfs.timeout,
                 max_concurrent_embedding=max_concurrent_embedding,
                 max_concurrent_semantic=max_concurrent_semantic,
             )
         else:
-            logger.warning("AGFS URL not configured, skipping queue manager initialization")
+            logger.warning("AGFS client not initialized, skipping queue manager")
 
         # Initialize VikingDBManager with QueueManager
         self._vikingdb_manager = VikingDBManager(
@@ -222,11 +229,10 @@ async def initialize(self) -> None:
         await init_context_collection(self._vikingdb_manager)
 
         self._viking_fs = init_viking_fs(
-            agfs_url=self._agfs_url or "http://localhost:8080",
+            agfs=self._agfs_client,
             query_embedder=self._embedder,
             rerank_config=config.rerank,
             vector_store=self._vikingdb_manager,
-            timeout=config.storage.agfs.timeout,
             enable_recorder=enable_recorder,
         )
         if enable_recorder: