zzos/OpenViking
1
0
Fork 0
mirror of https://github.com/volcengine/OpenViking.git synced 2026-09-29 16:58:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 修复 openviking serve 命令引用并更新贡献文档 (#357)

Browse Source 
openviking 入口已改为 Rust CLI，裸命令 `openviking serve` 不再可用，
将示例中的引用统一更新为 `openviking-server`。同时补充 CONTRIBUTING
文档中缺失的 Rust CLI 编译说明、修正测试示例和项目结构。

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Qin Haojie
2026-02-28 18:00:07 +08:00
committed by GitHub
co-authored by Claude Opus 4.6
parent c02b4e8b1a
commit a2d35cd264
8 changed files with 130 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+58 -20
View File
@@ -85,6 +85,22 @@ async def main():
asyncio.run(main())
```
### 5. Build Rust CLI (Optional)
The Rust CLI (`ov`) provides a high-performance command-line client for interacting with OpenViking Server.
**Prerequisites**: Rust >= 1.88
```bash
# Build and install from source
cargo install --path crates/ov_cli
# Or use the quick install script (downloads pre-built binary)
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash
```
After installation, run `ov --help` to see all available commands. CLI connection config goes in `~/.openviking/ovcli.conf`.
---
## Project Structure
@@ -92,6 +108,7 @@ asyncio.run(main())
```
openviking/
├── pyproject.toml # Project configuration
├── Cargo.toml # Rust workspace configuration
├── third_party/ # Third-party dependencies
│ └── agfs/ # AGFS filesystem
│
@@ -117,6 +134,11 @@ openviking/
│ │ ├── session.py # Session core
│ │ └── compressor.py # Compression
│ │
│ ├── server/ # HTTP server
│ │ ├── app.py # FastAPI app factory
│ │ ├── bootstrap.py # Entry point (openviking-server)
│ │ └── routers/ # API routers
│ │
│ ├── storage/ # Storage layer
│ │ ├── viking_fs.py # VikingFS
│ │ └── vectordb/ # Vector database
@@ -126,7 +148,21 @@ openviking/
│ │
│ └── prompts/ # Prompt templates
│
├── crates/ # Rust components
│ └── ov_cli/ # Rust CLI client
│ ├── src/ # CLI source code
│ └── install.sh # Quick install script
│
├── src/ # C++ extensions (pybind11)
│
├── tests/ # Test suite
│ ├── client/ # Client tests
│ ├── server/ # Server tests
│ ├── session/ # Session tests
│ ├── parse/ # Parser tests
│ ├── vectordb/ # Vector database tests
│ └── integration/ # Integration tests
│
└── docs/ # Documentation
├── en/ # English docs
└── zh/ # Chinese docs
@@ -190,48 +226,50 @@ mypy openviking/
# Run all tests
pytest
# Run specific test module
pytest tests/client/ -v
pytest tests/server/ -v
pytest tests/parse/ -v
# Run specific test file
pytest tests/test_parser.py
pytest tests/client/test_lifecycle.py
# Run specific test
pytest tests/client/test_lifecycle.py::TestClientInitialization::test_initialize_success
# Run by keyword
pytest -k "search" -v
# Run with coverage
pytest --cov=openviking --cov-report=term-missing
# Run with verbose output
pytest -v
```
### Writing Tests
Place test files in `tests/` directory with `test_*.py` naming:
Tests are organized in subdirectories under `tests/`. The project uses `asyncio_mode = "auto"`, so async tests do **not** need the `@pytest.mark.asyncio` decorator:
```python
# tests/test_client.py
import pytest
# tests/client/test_example.py
from openviking import AsyncOpenViking
class TestAsyncOpenViking:
@pytest.mark.asyncio
async def test_initialize(self, tmp_path):
client = AsyncOpenViking(path=str(tmp_path / "data"))
await client.initialize()
assert client._viking_fs is not None
await client.close()
@pytest.mark.asyncio
async def test_add_resource(self, tmp_path):
client = AsyncOpenViking(path=str(tmp_path / "data"))
await client.initialize()
async def test_initialize(self, uninitialized_client: AsyncOpenViking):
await uninitialized_client.initialize()
assert uninitialized_client._service is not None
await uninitialized_client.close()
async def test_add_resource(self, client: AsyncOpenViking):
result = await client.add_resource(
"./test.md",
reason="test document"
)
assert result["status"] == "success"
assert "root_uri" in result
await client.close()
```
Common fixtures are defined in `tests/conftest.py`, including `client` (initialized `AsyncOpenViking`), `uninitialized_client`, `temp_dir`, etc.
---
## Contribution Workflow
CONTRIBUTING_CN.md
+58 -20
View File
@@ -84,6 +84,22 @@ async def main():
asyncio.run(main())
```
### 5. 构建 Rust CLI（可选）
Rust CLI (`ov`) 提供高性能的命令行客户端，用于连接 OpenViking Server 进行操作。
**前置要求**：Rust >= 1.88
```bash
# 从源码编译安装
cargo install --path crates/ov_cli
# 或者使用一键安装脚本（下载预编译二进制）
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash
```
安装后通过 `ov --help` 查看所有可用命令。CLI 连接配置见 `~/.openviking/ovcli.conf`。
---
## 项目结构
@@ -91,6 +107,7 @@ asyncio.run(main())
```
openviking/
├── pyproject.toml # 项目配置
├── Cargo.toml # Rust workspace 配置
├── third_party/ # 第三方依赖
│ └── agfs/ # AGFS 文件系统
│
@@ -116,6 +133,11 @@ openviking/
│ │ ├── session.py # 会话核心
│ │ └── compressor.py # 压缩
│ │
│ ├── server/ # HTTP 服务端
│ │ ├── app.py # FastAPI 应用工厂
│ │ ├── bootstrap.py # 启动入口 (openviking-server)
│ │ └── routers/ # API 路由
│ │
│ ├── storage/ # 存储层
│ │ ├── viking_fs.py # VikingFS
│ │ └── vectordb/ # 向量数据库
@@ -125,7 +147,21 @@ openviking/
│ │
│ └── prompts/ # 提示词模板
│
├── crates/ # Rust 组件
│ └── ov_cli/ # Rust CLI 客户端
│ ├── src/ # CLI 源码
│ └── install.sh # 一键安装脚本
│
├── src/ # C++ 扩展 (pybind11)
│
├── tests/ # 测试套件
│ ├── client/ # 客户端测试
│ ├── server/ # 服务端测试
│ ├── session/ # 会话测试
│ ├── parse/ # 解析器测试
│ ├── vectordb/ # 向量数据库测试
│ └── integration/ # 集成测试
│
└── docs/ # 文档
├── en/ # 英文文档
└── zh/ # 中文文档
@@ -189,48 +225,50 @@ mypy openviking/
# 运行所有测试
pytest
# 运行特定测试模块
pytest tests/client/ -v
pytest tests/server/ -v
pytest tests/parse/ -v
# 运行特定测试文件
pytest tests/test_parser.py
pytest tests/client/test_lifecycle.py
# 运行特定测试
pytest tests/client/test_lifecycle.py::TestClientInitialization::test_initialize_success
# 按关键字运行
pytest -k "search" -v
# 运行并生成覆盖率报告
pytest --cov=openviking --cov-report=term-missing
# 详细输出模式运行
pytest -v
```
### 编写测试
将测试文件放在 `tests/` 目录下，命名为 `test_*.py`：
测试按模块组织在 `tests/` 的子目录中。项目使用 `asyncio_mode = "auto"`，异步测试**不需要** `@pytest.mark.asyncio` 装饰器：
```python
# tests/test_client.py
import pytest
# tests/client/test_example.py
from openviking import AsyncOpenViking
class TestAsyncOpenViking:
@pytest.mark.asyncio
async def test_initialize(self, tmp_path):
client = AsyncOpenViking(path=str(tmp_path / "data"))
await client.initialize()
assert client._viking_fs is not None
await client.close()
@pytest.mark.asyncio
async def test_add_resource(self, tmp_path):
client = AsyncOpenViking(path=str(tmp_path / "data"))
await client.initialize()
async def test_initialize(self, uninitialized_client: AsyncOpenViking):
await uninitialized_client.initialize()
assert uninitialized_client._service is not None
await uninitialized_client.close()
async def test_add_resource(self, client: AsyncOpenViking):
result = await client.add_resource(
"./test.md",
reason="test document"
)
assert result["status"] == "success"
assert "root_uri" in result
await client.close()
```
常用 fixture 定义在 `tests/conftest.py` 中，包括 `client`（已初始化的 `AsyncOpenViking`）、`uninitialized_client`、`temp_dir` 等。
---
## 贡献流程
examples/k8s-helm/templates/deployment.yaml
+1 -1
View File
@@ -24,7 +24,7 @@ spec:
- /bin/sh
- -c
- |
exec uv run --with openviking openviking serve \
exec uv run --with openviking openviking-server \
--host {{ .Values.server.host }} \
--port {{ .Values.server.port }} \
--config /etc/openviking/ov.conf
examples/multi_tenant/admin_workflow.sh
+1 -1
View File
@@ -10,7 +10,7 @@
# 1. Configure & start the server with root_api_key:
# Copy ov.conf.example to ov.conf, fill in your model API keys, then:
#
# openviking serve --config ./ov.conf
# openviking-server --config ./ov.conf
#
# The key config for multi-tenant auth:
# {
examples/server_client/README.md
+7 -7
View File
@@ -23,9 +23,9 @@ uv sync
# 参见 ov.conf.example 了解完整配置项
# 2. 启动 Server（另开终端）
openviking serve # 从默认路径读取 ov.conf
openviking serve --config ./ov.conf # 指定配置文件
openviking serve --host 0.0.0.0 --port 1933 # 覆盖 host/port
openviking-server # 从默认路径读取 ov.conf
openviking-server --config ./ov.conf # 指定配置文件
openviking-server --host 0.0.0.0 --port 1933 # 覆盖 host/port
# 3. 配置 CLI 连接（ovcli.conf）
# CLI 读取配置的优先级：
@@ -89,16 +89,16 @@ pyproject.toml # 项目依赖
```bash
# 基本启动（从 ~/.openviking/ov.conf 或 $OPENVIKING_CONFIG_FILE 读取配置）
openviking serve
openviking-server
# 指定配置文件
openviking serve --config ./ov.conf
openviking-server --config ./ov.conf
# 覆盖 host/port
openviking serve --host 0.0.0.0 --port 1933
openviking-server --host 0.0.0.0 --port 1933
```
`serve` 命令支持 `--config`、`--host`、`--port` 三个选项。认证密钥等其他配置通过 ov.conf 的 `server` 段设置。
`openviking-server` 命令支持 `--config`、`--host`、`--port` 三个选项。认证密钥等其他配置通过 ov.conf 的 `server` 段设置。
### Python 脚本
examples/server_client/client_async.py
+1 -1
View File
@@ -5,7 +5,7 @@ OpenViking 异步客户端示例 (HTTP mode)
使用 AsyncHTTPClient 通过 HTTP 连接远程 Server，演示完整 API。
前置条件:
先启动 Server: openviking serve
先启动 Server: openviking-server
运行:
uv run client_async.py
examples/server_client/client_cli.sh
+3 -3
View File
@@ -13,9 +13,9 @@
# b) ~/.openviking/ov.conf # default path
# See ov.conf.example for template.
#
# openviking serve # default: localhost:1933
# openviking serve --port 8080 # custom port
# openviking serve --config /path/to/ov.conf # explicit config path
# openviking-server # default: localhost:1933
# openviking-server --port 8080 # custom port
# openviking-server --config /path/to/ov.conf # explicit config path
#
# 2. Configure CLI connection (ovcli.conf):
# CLI reads ovcli.conf from (priority high → low):
examples/server_client/client_sync.py
+1 -1
View File
@@ -5,7 +5,7 @@ OpenViking 同步客户端示例 (HTTP mode)
使用 SyncHTTPClient 通过 HTTP 连接远程 Server，演示完整 API。
前置条件:
先启动 Server: openviking serve
先启动 Server: openviking-server
运行:
uv run client_sync.py