关注公众号
AI Agent Hermes Python 大模型

OpenViking 火山引擎配置指南

第一步：注册火山引擎账号

  1. 访问 https://www.volcengine.com/
  2. 使用手机号或邮箱注册账号
  3. 完成实名认证（新用户有免费额度）

第二步：开通火山方舟 (Volcano Ark)

  1. 登录火山引擎控制台
  2. 进入"火山方舟"服务页面
  3. 开通服务（新用户有免费试用额度）

第三步：创建 API Key

  1. 访问 API Key 管理页面：https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey
  2. 点击"创建新的 API Key"
  3. 复制并保存你的 API Key（格式通常为 sk-xxxxxxxxxxxx）

第四步：激活所需模型

4.1 激活 VLM 模型

  1. 访问模型管理页面：https://console.volcengine.com/ark/region:ark+cn-beijing/model
  2. 搜索并激活 doubao-seed-2-0-pro-260215
  3. 也可以使用 ark-code-latest 自动切换

4.2 激活 Embedding 模型

  1. 在同一模型管理页面
  2. 搜索并激活 doubao-embedding-vision-251215

第五步：配置 OpenViking

5.1 创建配置文件

配置文件位置：~/.openviking/ov.conf

将以下内容复制到配置文件中，并替换 YOUR_API_KEY_HERE 为你的实际 API Key：

{
  "storage": {
    "workspace": "D:/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "backend": "volcengine",
      "api_key": "sk-xxxxxxxxxxxx",
      "model": "doubao-embedding-vision-251215",
      "api_base": "https://ark.cn-beijing.volces.com/api/coding/v3",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "backend": "volcengine",
    "api_key": "sk-xxxxxxxxxxxx",
    "model": "doubao-seed-2-0-pro-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/coding/v3",
    "temperature": 0.1,
    "max_retries": 3
  }
}

5.2 设置环境变量

Windows PowerShell:

$env:OPENVIKING_CONFIG_FILE = "$HOME/.openviking/ov.conf"

Windows CMD:

set "OPENVIKING_CONFIG_FILE=%USERPROFILE%\.openviking\ov.conf"

Linux/macOS:

export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

第六步：安装 OpenViking

pip install openviking --upgrade --force-reinstall

验证安装：

openviking --version

第七步：测试连接

7.1 使用 Python SDK

import openviking as ov

# 初始化客户端
client = ov.OpenViking(path="./data")
client.initialize()

# 添加资源
add_result = client.add_resource(
    path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
)
root_uri = add_result['root_uri']

# 查看目录结构
ls_result = client.ls(root_uri)
print(f"Directory structure:\n{ls_result}\n")

# 等待语义处理完成
print("Waiting for semantic processing...")
client.wait_processed()

# 获取摘要和概览
abstract = client.abstract(root_uri)
overview = client.overview(root_uri)

print(f"L0 Abstract:\n{abstract}\n")
print(f"L1 Overview:\n{overview[:500]}...\n")

# 语义搜索
results = client.find("what is openviking", target_uri=root_uri)
print(f"Search results:\n{results}\n")

# 断开连接
client.disconnect()

7.2 使用 CLI 命令

# 添加资源
openviking add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md

# 搜索资源
openviking find "what is openviking"

# 健康检查
curl http://localhost:1933/health

免费额度说明

新用户福利

  • 火山引擎新用户：通常有 1-3 个月的免费试用期
  • 模型调用：VLM 和 Embedding 模型都有免费额度
  • 存储：OpenViking 本地存储免费

计费方式

  • VLM 模型：按输入/输出 Token 数计费
  • Embedding 模型：按文本长度计费
  • OpenViking 服务：开源版完全免费

常见问题

Q1: API Key 无效

  • 确保 API Key 以 sk- 开头
  • 从正确的区域页面获取（北京区域）
  • 检查是否过期或被禁用

Q2: 模型未激活

  • 前往模型管理页面确认模型已激活
  • 使用正确的模型 ID（注意版本号）

Q3: 网络连接问题

  • 检查防火墙设置
  • 确认 API Base URL 正确
  • 尝试使用代理（如有需要）

Q4: 安装失败

  • 确保 Python 版本 >= 3.10
  • 使用国内镜像源加速安装
  • 清除缓存后重新安装

进阶配置

多区域支持

{
  "embedding": {
    "dense": {
      "api_base": "https://ark.cn-shanghai.volces.com/api/coding/v3"
    }
  },
  "vlm": {
    "api_base": "https://ark.cn-shanghai.volces.com/api/coding/v3"
  }
}

自定义模型

{
  "vlm": {
    "model": "ark-code-latest"
  }
}

下一步

  1. 集成到现有的 AI Agent 框架（如 OpenClaw、Hermes）
  2. 配置记忆持久化和自动更新
  3. 探索高级检索和语义分析功能
  4. 参与 OpenViking 社区获取支持

官方资源：

← 返回文章列表