openviking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenViking Skill

Manage an OpenViking context database: index documents, semantic search, browse, and retrieve summaries.

管理OpenViking上下文数据库：索引文档、语义搜索、浏览及检索摘要。

Prerequisites

前置条件

Python 3.9+ with
```
openviking
```
package installed (
```
pip install openviking
```
)
Config file at
```
~/.openviking/ov.conf
```
with valid embedding and VLM credentials

Environment variable

OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

If prerequisites are not met, guide the user through setup. See

references/setup-guide.md

安装Python 3.9+及
```
openviking
```
包（执行
```
pip install openviking
```
）
在
```
~/.openviking/ov.conf
```
路径下存在配置文件，且包含有效的embedding和VLM凭证

设置环境变量

OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

若未满足前置条件，请引导用户完成设置。详见

references/setup-guide.md

。

Quick Reference

快速参考

Index a file

索引单个文件

bash

python3 scripts/viking.py add /path/to/file.md

bash

python3 scripts/viking.py add /path/to/file.md

Index all files in a directory (recursive)

索引目录下所有文件（递归）

bash

python3 scripts/viking.py add-dir /path/to/directory --pattern "*.md"

bash

python3 scripts/viking.py add-dir /path/to/directory --pattern "*.md"

Semantic search

语义搜索

bash

python3 scripts/viking.py search "query text" --limit 5

bash

python3 scripts/viking.py search "query text" --limit 5

Browse resources

浏览资源

bash

python3 scripts/viking.py ls [viking://resources/path]

bash

python3 scripts/viking.py ls [viking://resources/path]

Get summary

获取摘要

bash

python3 scripts/viking.py abstract viking://resources/my_doc
python3 scripts/viking.py overview viking://resources/my_doc

bash

python3 scripts/viking.py abstract viking://resources/my_doc
python3 scripts/viking.py overview viking://resources/my_doc

Read full content

读取完整内容

bash

python3 scripts/viking.py read viking://resources/my_doc/section.md

bash

python3 scripts/viking.py read viking://resources/my_doc/section.md

Usage Notes

使用注意事项

Data directory: Defaults to
```
./openviking_data
```
in the current working directory. Override with
```
--data-dir
```
.
File name collisions: OpenViking uses file names (not full paths) as URIs. Avoid indexing files with identical names from different directories simultaneously.
VLM model: Use non-reasoning models (e.g.
```
meta/llama-3.3-70b-instruct
```
) for the VLM. Reasoning models return content in the wrong field.
Embedding model:
```
nvidia/nv-embed-v1
```
(symmetric, 4096-dim) works without extra parameters. Asymmetric models (e.g.
```
nv-embedqa-e5-v5
```
) require
```
input_type
```
which OpenViking doesn't pass.

数据目录：默认位于当前工作目录下的
```
./openviking_data
```
，可通过
```
--data-dir
```
参数覆盖。
文件名冲突：OpenViking使用文件名（而非完整路径）作为URI。请避免同时索引来自不同目录的同名文件。
VLM模型：VLM请使用非推理模型（例如
```
meta/llama-3.3-70b-instruct
```
）。推理模型会返回错误字段的内容。
Embedding模型：
```
nvidia/nv-embed-v1
```
（对称模型，4096维度）无需额外参数即可使用。非对称模型（例如
```
nv-embedqa-e5-v5
```
）需要
```
input_type
```
参数，但OpenViking不会传递该参数。

When to Use Python API vs CLI Script

Python API与CLI脚本的适用场景

CLI script (
```
scripts/viking.py
```
): For quick one-off operations from the shell.
Python API: For complex workflows, batch operations, or integration into other scripts. See
```
references/python-api.md
```
.

CLI脚本（
```
scripts/viking.py
```
）：适用于在Shell中执行快速一次性操作。
Python API：适用于复杂工作流、批量操作或集成到其他脚本中。详见
```
references/python-api.md
```
。