Skip to content

refactor(client): 拆分 HTTP 客户端，分离嵌入模式与 HTTP 模式 #141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MaojiaSheng merged 2 commits into from
Feb 12, 2026
Merged

refactor(client): 拆分 HTTP 客户端，分离嵌入模式与 HTTP 模式 #141

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e30ef4a
refactor(client): 拆分 HTTP 客户端，分离嵌入模式与 HTTP 模式
qin-ctx Feb 12, 2026
4976ac5
fix queue
qin-ctx Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions docs/design/server_client/server-cli-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -345,10 +345,10 @@ OpenViking 提供三种接口，面向不同使用场景：

```python
# 构造函数参数
client = OpenViking(url="http://localhost:1933", api_key="your-api-key", user="alice")
client = SyncHTTPClient(url="http://localhost:1933", api_key="your-api-key")
```

SDK 构造函数只接受 `url`、`api_key`、`path`、`user` 参数。不支持 `config` 参数，也不支持 `vectordb_url`/`agfs_url` 参数。
SDK 构造函数只接受 `url`、`api_key`、`path` 参数。不支持 `config` 参数，也不支持 `vectordb_url`/`agfs_url` 参数。

#### CLI 配置

Expand All @@ -358,7 +358,6 @@ CLI 通过 `ovcli.conf` 配置文件管理连接信息，不使用 `--url`、`--
{
"url": "http://localhost:1933",
"api_key": "sk-xxx",
"user": "alice",
"output": "table"
}
```
Expand Down Expand Up @@ -652,7 +651,7 @@ class UsageInfo:
**session**（Python CLI 返回 Session 对象，HTTP API 返回 JSON）
```python
# Python CLI
session = client.session(user="alice")
session = client.session()
session.id # "session-abc123"
session.user # "alice"
session.created_at # datetime
Expand Down Expand Up @@ -871,7 +870,6 @@ export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf
# {
# "url": "http://localhost:1933",
# "api_key": "sk-xxx",
# "user": "alice",
# "output": "table"
# }

Expand Down Expand Up @@ -1024,7 +1022,7 @@ for r in results.data.results:
print(f"{r.uri}: {r.score:.2f}")

# 会话管理（OOP 模式）
session = client.session(user="alice")
session = client.session()
session.add_message("user", "What is OpenViking?")
results = client.search("What is OpenViking?", session=session)

Expand Down
89 changes: 73 additions & 16 deletions docs/en/api/01-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,38 +21,78 @@ client = ov.OpenViking(path="./data")
client.initialize()
```

Embedded mode uses `ov.conf` to configure embedding, vlm, storage, and other modules. Default path: `~/.openviking/ov.conf`. You can also specify the path via environment variable:

```bash
export OPENVIKING_CONFIG_FILE=/path/to/ov.conf
```

Minimal configuration example:

```json
{
"embedding": {
"dense": {
"api_base": "<api-endpoint>",
"api_key": "<your-api-key>",
"provider": "<volcengine|openai>",
"dimension": 1024,
"model": "<model-name>"
}
},
"vlm": {
"api_base": "<api-endpoint>",
"api_key": "<your-api-key>",
"provider": "<volcengine|openai>",
"model": "<model-name>"
}
}
```

For full configuration options and provider-specific examples, see the [Configuration Guide](../guides/01-configuration.md).

### HTTP Mode

```python
client = ov.OpenViking(
client = ov.SyncHTTPClient(
url="http://localhost:1933",
api_key="your-key",
)
client.initialize()
```

### Direct HTTP (curl)
When `url` is not explicitly provided, the HTTP client automatically loads connection info from `ovcli.conf`. This config file is shared between the HTTP client and CLI. Default path: `~/.openviking/ovcli.conf`. You can also specify the path via environment variable:

```bash
curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
-H "X-API-Key: your-key"
export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
```

### CLI Mode

The CLI connects to an OpenViking server and exposes all operations as shell commands.

**Configuration**

Create `~/.openviking/ovcli.conf` (or set `OPENVIKING_CLI_CONFIG_FILE` environment variable):

```json
{
"url": "http://localhost:1933",
"api_key": "your-key"
}
```

| Field | Description | Default |
|-------|-------------|---------|
| `url` | Server address | (required) |
| `api_key` | API key | `null` (no auth) |
| `output` | Default output format: `"table"` or `"json"` | `"table"` |

See the [Configuration Guide](../guides/01-configuration.md#ovcliconf) for details.

### Direct HTTP (curl)

```bash
curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
-H "X-API-Key: your-key"
```

### CLI Mode

The CLI connects to an OpenViking server and exposes all operations as shell commands. The CLI also loads connection info from `ovcli.conf` (shared with the HTTP client).

**Basic Usage**

```bash
Expand All @@ -74,15 +114,32 @@ openviking --json ls viking://resources/
openviking -o json ls viking://resources/
```

## Client Lifecycle
## Lifecycle

**Embedded Mode**

```python
client = ov.OpenViking(path="./data") # or url="http://..."
client.initialize() # Required before any operations
import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

# ... use client ...

client.close()
```

**HTTP Mode**

```python
import openviking as ov

client = ov.SyncHTTPClient(url="http://localhost:1933")
client.initialize()

# ... use client ...

client.close() # Release resources
client.close()
```

## Authentication
Expand Down
43 changes: 12 additions & 31 deletions docs/en/api/02-resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,22 +46,16 @@ Add a resource to the knowledge base.
| wait | bool | No | False | Wait for semantic processing to complete |
| timeout | float | No | None | Timeout in seconds (only used when wait=True) |

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

result = client.add_resource(
"./documents/guide.md",
reason="User guide documentation"
)
print(f"Added: {result['root_uri']}")

client.wait_processed()
client.close()
```

**HTTP API**
Expand Down Expand Up @@ -103,7 +97,7 @@ openviking add-resource ./documents/guide.md --reason "User guide documentation"

**Example: Add from URL**

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
result = client.add_resource(
Expand Down Expand Up @@ -136,7 +130,7 @@ openviking add-resource https://example.com/api-docs.md --to viking://resources/

**Example: Wait for Processing**

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
# Option 1: Wait inline
Expand Down Expand Up @@ -187,21 +181,14 @@ Export a resource tree as a `.ovpack` file.
| uri | str | Yes | - | Viking URI to export |
| to | str | Yes | - | Target file path |

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

path = client.export_ovpack(
"viking://resources/my-project/",
"./exports/my-project.ovpack"
)
print(f"Exported to: {path}")

client.close()
```

**HTTP API**
Expand Down Expand Up @@ -253,14 +240,9 @@ Import a `.ovpack` file.
| force | bool | No | False | Overwrite existing resources |
| vectorize | bool | No | True | Trigger vectorization after import |

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

uri = client.import_ovpack(
"./exports/my-project.ovpack",
"viking://resources/imported/",
Expand All @@ -270,7 +252,6 @@ uri = client.import_ovpack(
print(f"Imported to: {uri}")

client.wait_processed()
client.close()
```

**HTTP API**
Expand Down Expand Up @@ -315,7 +296,7 @@ openviking import ./exports/my-project.ovpack viking://resources/imported/ --for

### List Resources

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
# List all resources
Expand Down Expand Up @@ -388,7 +369,7 @@ openviking ls viking://resources/ --recursive

### Read Resource Content

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
# L0: Abstract
Expand Down Expand Up @@ -444,7 +425,7 @@ openviking read viking://resources/docs/api.md

### Move Resources

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
client.mv(
Expand Down Expand Up @@ -492,7 +473,7 @@ openviking mv viking://resources/old-project/ viking://resources/new-project/

### Delete Resources

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
# Delete single file
Expand Down Expand Up @@ -544,7 +525,7 @@ openviking rm viking://resources/old-project/ --recursive

### Create Links

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
# Link related resources
Expand Down Expand Up @@ -616,7 +597,7 @@ openviking link viking://resources/docs/auth/ viking://resources/docs/security/

### Get Relations

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
relations = client.relations("viking://resources/docs/auth/")
Expand Down Expand Up @@ -658,7 +639,7 @@ openviking relations viking://resources/docs/auth/

### Remove Links

**Python SDK**
**Python SDK (Embedded / HTTP)**

```python
client.unlink(
Expand Down
Loading
Loading