OpenViking 服务模式快速上手指南从单机 HTTP 服务到 ECS 云端部署【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 除了可以作为本地 Python 库使用外还支持以独立 HTTP 服务Server Mode运行让任意客户端通过网络接入统一的知识库与 Agent 记忆。本文基于 docs/en/getting-started/03-quickstart-server.md 展开完整覆盖服务模式的启动前置条件、openviking-server init/doctor校验流程、Python SDK / CLI / curl 三类客户端接入、两级 API Key 认证模型以及基于 Volcengine ECS 的云端部署实战。读完后你将掌握从零启动一个 OpenViking 服务、用三种客户端完成资源入库与语义检索、并在云服务器上以守护进程方式长期运行的完整能力。一、前置条件与安装1. 安装 OpenViking服务模式需要同时具备openviking-server服务端命令与openviking客户端命令ov为其别名推荐通过包管理器安装pip install openviking --upgrade --force-reinstall如果你偏好uv或pipx同样可以安装详见 02-quickstart.md# uv推荐 uv tool install openviking --upgrade # pipx pipx install openviking安装完成后即获得两个命令ov/openviking作为客户端命令openviking-server作为服务端命令。2. 模型配置就绪服务模式依赖 VLM图像与内容理解与 Embedding向量化与语义检索两类模型能力请先按 02-quickstart.md 完成模型准备与ov.conf配置。支持 Volcengine豆包模型、OpenAI、OpenAI Codex 以及任何 OpenAI 兼容格式的自定义模型服务。3. Python 3.14 的 Volcengine Ark 特别提示如果你的ov.conf使用provider volcengineArk 运行时目前建议openviking-server运行在 Python 3.13 或更低版本。volcengine-python-sdk[ark]在 Python 3.14 上仍会输出 Pydantic V1 兼容性警告服务本身可以工作但启动/版本命令可能打印大量噪声日志直到上游 SDK 移除该兼容层。二、启动服务器init → doctor → run1. 首次初始化openviking-server init确保配置文件位于~/.openviking/ov.conf模型与存储设置见 01-configuration.md。首次使用请先执行初始化向导openviking-server init从源码看init子命令由 openviking_cli/server_bootstrap.py 直接拦截处理跳转到 openviking_cli/setup_wizard.py 中的交互式向导。向导会分别引导你选择 Embedding 与 VLM 配置对于 OpenAI、Volcengine、Kimi、GLM 等 API 型 VLM会提示输入 API Key如果选择 OpenAI Codex 作为 VLM向导可以导入已有的 Codex 认证或直接引导你完成登录。它还内置了 Ollama 检测与安装辅助方便 macOS / Apple Silicon 用户走本地部署路径。2. 启动前自检openviking-server doctoropenviking-server doctor在不启动服务的前提下校验本地配置与运行环境是否可用包括 provider 相关的认证就绪状态。它只检查本地环境与ov health探测已运行的服务进程是不同的概念。openviking-server doctor结合 openviking_cli/doctor.py 源码doctor实际执行了 10 项检查_CHECKS列表每项输出PASS / WARN / FAIL状态失败时还会给出可执行的修复建议检查项说明Configov.conf是否存在、JSON 是否合法、是否包含必要字段会用与服务端启动相同的解析逻辑校验未知或非法字段Python版本必须 3.10Native Engine原生向量引擎PersistStore变体在当前平台是否可用AGFS内置 AGFS 客户端能否加载Authentication基于server.auth_mode运行认证健康检查API Key / OIDC / LDAP / Trusted / DevEmbedding读取embedding.dense配置向 provider 发送一次真实探针请求并校验向量维度如dimension1024与实际输出不匹配会失败VLM校验vlm段结构与凭据openai-codex会检查 OAuth 状态Ollama若配置使用了 Ollamaembedding / VLM / query_planner检测ollama serve是否可达VikingBot校验可选组件 VikingBot 与当前服务认证模式的对齐情况缺失时仅警告Disk工作区所在磁盘至少需要约 1 GB 可用空间因此openviking-server doctor是启动前最有价值的排雷手段——它会在你真正启动服务之前把配置错误、维度不匹配、密钥缺失、网络不可达等问题一次性暴露出来。3. 启动服务配置文件位于默认路径~/.openviking/ov.conf时直接启动# 默认路径配置 —— 直接启动 openviking-server # 配置文件在其它位置 —— 用 --config 指定 openviking-server --config /path/to/ov.conf # 覆盖监听端口 openviking-server --port 8000成功启动后终端会输出类似INFO: Uvicorn running on http://0.0.0.0:1933关于--config的底层行为从 openviking_cli/server_bootstrap.py 可以看到openviking-server在导入任何openviking模块之前会先从sys.argv预解析--config参数并写入OPENVIKING_CONFIG_FILE环境变量从而保证配置单例初始化时就能读到正确路径——该逻辑对init、doctor、正常启动三个子命令一致生效。三、验证服务/health 与 Web Studiocurl http://localhost:1933/health # {status: ok}两者定位不同openviking-server doctor检查的是本地配置、模型访问与认证就绪curl /health只确认服务进程已经在运行返回{status: ok}且该端点永不要求认证便于负载均衡与监控探活。此外Web Studio 也托管在同一端口的/studio路径http://localhost:1933/studio。从 openviking/server/app.py 源码可见服务启动时会检查内置的 Web Studio 静态资源目录存在则挂载/studio并让裸访问根路径 302 重定向到/studio/。自 v0.3.21 起 Web Studio 已随 pip / pipx 安装包内置无需 Docker。四、客户端接入方式一Python SDK1. 基础连接import openviking as ov client ov.SyncHTTPClient(urlhttp://localhost:1933)2. 认证两级 API Key 系统当服务端启用了认证需要传入 API Key。OpenViking 采用两级 Key 体系详见 04-authentication.md常规数据访问使用user_key推荐大多数场景下应使用user_key——它可以直接调用租户级 APIadd_resource、find、ls等import openviking as ov client ov.SyncHTTPClient( urlhttp://localhost:1933, api_keyuser-key, )user_key通过 Admin API 创建见 04-authentication.md。服务端可以从 Key 自动解析出所属租户tenant。管理操作使用root_keyroot_key仅用于管理类操作创建账号、查看系统状态等。租户级数据 APIadd_resource、find、会话等需要绑定到账号/用户的 Key如 user key 或 admin keyimport openviking as ov client ov.SyncHTTPClient( urlhttp://localhost:1933, api_keyuser-or-admin-key, )在api_key模式下用root_key调用租户级数据 API 会返回PERMISSION_DENIED。数据访问请使用 user/admin key若需上游身份断言请使用 trusted 模式详见 04-authentication.md含 trusted 模式与 CLI 配置。两级 Key 的角色模型Root Key 由服务端配置root_api_key指定角色为 ROOT负责账号管理与系统/监控操作User Key 由 Admin API 生成角色为 ADMIN 或 USER负责各自账号内的数据访问ADMIN 还可管理其账号内的用户。客户端可通过X-API-Key头或Authorization: Bearer key两种方式携带 Key。3. 完整示例使用 user_keyimport openviking as ov client ov.SyncHTTPClient(urlhttp://localhost:1933) try: client.initialize() # 添加资源 result client.add_resource( pathhttps://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md, ) root_uri result[root_uri] # 等待语义处理完成 client.wait_processed() # 语义检索 results client.find( querywhat is openviking, target_uriroot_uri, ) for result in results.get(resources, []): print(f {result[uri]} (score: {result.get(score, 0.0):.4f})) finally: client.close()五、客户端接入方式二CLI1. 创建 CLI 配置文件创建~/.openviking/ovcli.conf指向你的服务端{ url: http://localhost:1933, api_key: your-key }2. 常用命令# 检查系统健康 openviking observer system # 将资源加入记忆 openviking add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md # 列出所有已同步资源 openviking ls viking://resources # 查询 openviking find what is openviking3. 自定义配置文件路径配置文件位于其它位置时通过环境变量指定export OPENVIKING_CLI_CONFIG_FILE/path/to/ovcli.conf六、客户端接入方式三curl裸 HTTP远程 URL 资源可以直接传入path本地文件需先通过POST /api/v1/resources/temp_upload上传拿到返回的temp_file_id后再调用目标 API本地目录在裸 HTTP 模式下需先打成.zip上传。# 添加资源 curl -X POST http://localhost:1933/api/v1/resources \ -H Content-Type: application/json \ -d {path: https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md} # 列出资源 curl http://localhost:1933/api/v1/fs/ls?uriviking://resources/ # 语义检索 curl -X POST http://localhost:1933/api/v1/search/find \ -H Content-Type: application/json \ -d {query: what is openviking}启用认证后为上述请求追加-H X-API-Key: user-key或-H Authorization: Bearer user-key即可参见 04-authentication.md。七、云端部署实战Volcengine ECS为获得高性能、可扩展的 Context Memory为 Agent 提供可靠的长期记忆推荐部署在Volcengine Elastic Compute ServiceECS上操作系统使用veLinux。1. 实例开通与配置项目推荐配置说明镜像veLinux 2.0CentOS 兼容勾选安全加固实例规格计算型 c3a2 vCPU4GiB 以上满足基础推理与检索需求存储增加 256 GiB 数据盘用于向量数据持久化网络按需配置仅开放必要业务端口如 TCP 19332. 环境准备挂载数据盘实例运行后需将数据盘挂载到/data目录。以下脚本自动完成格式化与挂载# 1. 创建挂载点 mkdir -p /data # 2. 配置自动挂载使用 UUID 防止盘符漂移 cp /etc/fstab /etc/fstab.bak DISK_UUID$(blkid -s UUID -o value /dev/vdb) if [ -z $DISK_UUID ]; then echo ERROR: /dev/vdb UUID not found else # 追加到 fstab echo UUID${DISK_UUID} /data ext4 defaults,nofail 0 0 /etc/fstab # 校验并挂载 mount -a echo Mount successful. Current disk status: df -Th /data fi3. 安装依赖与 OpenVikingyum install -y curl git tree # 第 1 步安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 第 2 步配置环境变量 echo source $HOME/.cargo/env ~/.bashrc source ~/.bashrc # 验证安装 uv --version # 第 3 步在数据盘上创建虚拟环境 cd /data uv venv ovenv --python 3.11 # 第 4 步激活虚拟环境 source /data/ovenv/bin/activate # 第 5 步验证 echo Ready echo Python path: $(which python) echo Python version: $(python --version)在已激活的虚拟环境中安装 OpenVikinguv tool install openviking --upgrade4. 服务端配置与启动准备配置文件# 创建配置目录 mkdir -p ~/.openviking # 创建并编辑配置文件 vim ~/.openviking/ov.conf配置模板{ embedding: { dense: { api_base : api-endpoint, // e.g., https://ark.cn-beijing.volces.com/api/v3 api_key : your-api-key, // Model service API Key provider : provider-type, // volcengine or openai dimension: 1024, // Vector dimension model : model-name, // e.g., doubao-embedding-vision-251215 input : multimodal // Use multimodal for doubao-embedding-vision models } }, vlm: { api_base : api-endpoint, api_key : your-api-key, provider : provider-type, max_retries: 2, model : model-name // e.g., doubao-seed-2-0-lite-260428 or gpt-4-vision-preview } }提示在 vim 中按i进入插入模式粘贴配置然后按Esc输入:wq保存退出。各字段的深层含义可参考 01-configuration.mdembedding.dense.dimension必须与模型实际输出维度一致如豆包视觉向量模型为 1024input: multimodal允许对文本、图片及混合内容做向量化图像检索必须使用该模式vlm.max_retries仅对 429、5xx、超时等瞬时错误生效重试采用带抖动的指数退避0.5s 起、8s 封顶。后台启动服务source /data/ovenv/bin/activate mkdir -p /data/log/ nohup openviking-server /data/log/openviking.log 21 # 注意数据将存储在相对执行路径的 ./data 目录下 # 停止服务pkill openviking; pkill agfs注意生产环境如需故障自动重启建议使用systemctl托管本指南不展开可参考 03-deployment.md 中的 systemd 单元文件示例。验证服务状态# 检查进程 ps aux | grep openviking-server # 查看日志 tail -f /data/log/openviking.log5. 客户端配置与测试CLI确保本机也安装了openviking以使用 CLI并将ovcli.conf指向你的服务器地址。vim ~/.openviking/ovcli.conf写入以下内容替换为服务器 IP{ url: http://XXX.XXX.XXX.XXX:1933, api_key: your-key }监控系统健康openviking observer system功能测试上传与检索# 上传测试资源 openviking add-resource https://raw.githubusercontent.com/ZaynJarvis/doc-eval/refs/heads/main/text.md # 列出资源 openviking ls viking://resources # 测试检索 openviking find who is Alice八、安全与生产化要点认证必配默认host为127.0.0.1。一旦将服务暴露到网络上必须配置root_api_keyserver.root_api_key否则服务会拒绝启动server.auth_mode未显式配置时设置了root_api_key会自动进入api_key模式未设置则进入仅限本机的dev模式详见 04-authentication.md。健康检查/health为存活探针Liveness/ready为就绪探针Readiness会检查 AGFS、VectorDB、APIKeyManager、Embedding、Ollama分别对应 K8s 的两种探针场景详见 03-deployment.md。进程管理ECS 场景使用nohup后台运行生产环境推荐 systemd 托管实现开机自启与崩溃自动重启。下一步Server Deployment - 配置、认证与部署选项全解API Overview - 完整 API 参考Authentication - 使用 API Key 保护你的服务端【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenViking 服务模式快速上手指南：从单机 HTTP 服务到 ECS 云端部署
OpenViking 服务模式快速上手指南从单机 HTTP 服务到 ECS 云端部署【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 除了可以作为本地 Python 库使用外还支持以独立 HTTP 服务Server Mode运行让任意客户端通过网络接入统一的知识库与 Agent 记忆。本文基于 docs/en/getting-started/03-quickstart-server.md 展开完整覆盖服务模式的启动前置条件、openviking-server init/doctor校验流程、Python SDK / CLI / curl 三类客户端接入、两级 API Key 认证模型以及基于 Volcengine ECS 的云端部署实战。读完后你将掌握从零启动一个 OpenViking 服务、用三种客户端完成资源入库与语义检索、并在云服务器上以守护进程方式长期运行的完整能力。一、前置条件与安装1. 安装 OpenViking服务模式需要同时具备openviking-server服务端命令与openviking客户端命令ov为其别名推荐通过包管理器安装pip install openviking --upgrade --force-reinstall如果你偏好uv或pipx同样可以安装详见 02-quickstart.md# uv推荐 uv tool install openviking --upgrade # pipx pipx install openviking安装完成后即获得两个命令ov/openviking作为客户端命令openviking-server作为服务端命令。2. 模型配置就绪服务模式依赖 VLM图像与内容理解与 Embedding向量化与语义检索两类模型能力请先按 02-quickstart.md 完成模型准备与ov.conf配置。支持 Volcengine豆包模型、OpenAI、OpenAI Codex 以及任何 OpenAI 兼容格式的自定义模型服务。3. Python 3.14 的 Volcengine Ark 特别提示如果你的ov.conf使用provider volcengineArk 运行时目前建议openviking-server运行在 Python 3.13 或更低版本。volcengine-python-sdk[ark]在 Python 3.14 上仍会输出 Pydantic V1 兼容性警告服务本身可以工作但启动/版本命令可能打印大量噪声日志直到上游 SDK 移除该兼容层。二、启动服务器init → doctor → run1. 首次初始化openviking-server init确保配置文件位于~/.openviking/ov.conf模型与存储设置见 01-configuration.md。首次使用请先执行初始化向导openviking-server init从源码看init子命令由 openviking_cli/server_bootstrap.py 直接拦截处理跳转到 openviking_cli/setup_wizard.py 中的交互式向导。向导会分别引导你选择 Embedding 与 VLM 配置对于 OpenAI、Volcengine、Kimi、GLM 等 API 型 VLM会提示输入 API Key如果选择 OpenAI Codex 作为 VLM向导可以导入已有的 Codex 认证或直接引导你完成登录。它还内置了 Ollama 检测与安装辅助方便 macOS / Apple Silicon 用户走本地部署路径。2. 启动前自检openviking-server doctoropenviking-server doctor在不启动服务的前提下校验本地配置与运行环境是否可用包括 provider 相关的认证就绪状态。它只检查本地环境与ov health探测已运行的服务进程是不同的概念。openviking-server doctor结合 openviking_cli/doctor.py 源码doctor实际执行了 10 项检查_CHECKS列表每项输出PASS / WARN / FAIL状态失败时还会给出可执行的修复建议检查项说明Configov.conf是否存在、JSON 是否合法、是否包含必要字段会用与服务端启动相同的解析逻辑校验未知或非法字段Python版本必须 3.10Native Engine原生向量引擎PersistStore变体在当前平台是否可用AGFS内置 AGFS 客户端能否加载Authentication基于server.auth_mode运行认证健康检查API Key / OIDC / LDAP / Trusted / DevEmbedding读取embedding.dense配置向 provider 发送一次真实探针请求并校验向量维度如dimension1024与实际输出不匹配会失败VLM校验vlm段结构与凭据openai-codex会检查 OAuth 状态Ollama若配置使用了 Ollamaembedding / VLM / query_planner检测ollama serve是否可达VikingBot校验可选组件 VikingBot 与当前服务认证模式的对齐情况缺失时仅警告Disk工作区所在磁盘至少需要约 1 GB 可用空间因此openviking-server doctor是启动前最有价值的排雷手段——它会在你真正启动服务之前把配置错误、维度不匹配、密钥缺失、网络不可达等问题一次性暴露出来。3. 启动服务配置文件位于默认路径~/.openviking/ov.conf时直接启动# 默认路径配置 —— 直接启动 openviking-server # 配置文件在其它位置 —— 用 --config 指定 openviking-server --config /path/to/ov.conf # 覆盖监听端口 openviking-server --port 8000成功启动后终端会输出类似INFO: Uvicorn running on http://0.0.0.0:1933关于--config的底层行为从 openviking_cli/server_bootstrap.py 可以看到openviking-server在导入任何openviking模块之前会先从sys.argv预解析--config参数并写入OPENVIKING_CONFIG_FILE环境变量从而保证配置单例初始化时就能读到正确路径——该逻辑对init、doctor、正常启动三个子命令一致生效。三、验证服务/health 与 Web Studiocurl http://localhost:1933/health # {status: ok}两者定位不同openviking-server doctor检查的是本地配置、模型访问与认证就绪curl /health只确认服务进程已经在运行返回{status: ok}且该端点永不要求认证便于负载均衡与监控探活。此外Web Studio 也托管在同一端口的/studio路径http://localhost:1933/studio。从 openviking/server/app.py 源码可见服务启动时会检查内置的 Web Studio 静态资源目录存在则挂载/studio并让裸访问根路径 302 重定向到/studio/。自 v0.3.21 起 Web Studio 已随 pip / pipx 安装包内置无需 Docker。四、客户端接入方式一Python SDK1. 基础连接import openviking as ov client ov.SyncHTTPClient(urlhttp://localhost:1933)2. 认证两级 API Key 系统当服务端启用了认证需要传入 API Key。OpenViking 采用两级 Key 体系详见 04-authentication.md常规数据访问使用user_key推荐大多数场景下应使用user_key——它可以直接调用租户级 APIadd_resource、find、ls等import openviking as ov client ov.SyncHTTPClient( urlhttp://localhost:1933, api_keyuser-key, )user_key通过 Admin API 创建见 04-authentication.md。服务端可以从 Key 自动解析出所属租户tenant。管理操作使用root_keyroot_key仅用于管理类操作创建账号、查看系统状态等。租户级数据 APIadd_resource、find、会话等需要绑定到账号/用户的 Key如 user key 或 admin keyimport openviking as ov client ov.SyncHTTPClient( urlhttp://localhost:1933, api_keyuser-or-admin-key, )在api_key模式下用root_key调用租户级数据 API 会返回PERMISSION_DENIED。数据访问请使用 user/admin key若需上游身份断言请使用 trusted 模式详见 04-authentication.md含 trusted 模式与 CLI 配置。两级 Key 的角色模型Root Key 由服务端配置root_api_key指定角色为 ROOT负责账号管理与系统/监控操作User Key 由 Admin API 生成角色为 ADMIN 或 USER负责各自账号内的数据访问ADMIN 还可管理其账号内的用户。客户端可通过X-API-Key头或Authorization: Bearer key两种方式携带 Key。3. 完整示例使用 user_keyimport openviking as ov client ov.SyncHTTPClient(urlhttp://localhost:1933) try: client.initialize() # 添加资源 result client.add_resource( pathhttps://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md, ) root_uri result[root_uri] # 等待语义处理完成 client.wait_processed() # 语义检索 results client.find( querywhat is openviking, target_uriroot_uri, ) for result in results.get(resources, []): print(f {result[uri]} (score: {result.get(score, 0.0):.4f})) finally: client.close()五、客户端接入方式二CLI1. 创建 CLI 配置文件创建~/.openviking/ovcli.conf指向你的服务端{ url: http://localhost:1933, api_key: your-key }2. 常用命令# 检查系统健康 openviking observer system # 将资源加入记忆 openviking add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md # 列出所有已同步资源 openviking ls viking://resources # 查询 openviking find what is openviking3. 自定义配置文件路径配置文件位于其它位置时通过环境变量指定export OPENVIKING_CLI_CONFIG_FILE/path/to/ovcli.conf六、客户端接入方式三curl裸 HTTP远程 URL 资源可以直接传入path本地文件需先通过POST /api/v1/resources/temp_upload上传拿到返回的temp_file_id后再调用目标 API本地目录在裸 HTTP 模式下需先打成.zip上传。# 添加资源 curl -X POST http://localhost:1933/api/v1/resources \ -H Content-Type: application/json \ -d {path: https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md} # 列出资源 curl http://localhost:1933/api/v1/fs/ls?uriviking://resources/ # 语义检索 curl -X POST http://localhost:1933/api/v1/search/find \ -H Content-Type: application/json \ -d {query: what is openviking}启用认证后为上述请求追加-H X-API-Key: user-key或-H Authorization: Bearer user-key即可参见 04-authentication.md。七、云端部署实战Volcengine ECS为获得高性能、可扩展的 Context Memory为 Agent 提供可靠的长期记忆推荐部署在Volcengine Elastic Compute ServiceECS上操作系统使用veLinux。1. 实例开通与配置项目推荐配置说明镜像veLinux 2.0CentOS 兼容勾选安全加固实例规格计算型 c3a2 vCPU4GiB 以上满足基础推理与检索需求存储增加 256 GiB 数据盘用于向量数据持久化网络按需配置仅开放必要业务端口如 TCP 19332. 环境准备挂载数据盘实例运行后需将数据盘挂载到/data目录。以下脚本自动完成格式化与挂载# 1. 创建挂载点 mkdir -p /data # 2. 配置自动挂载使用 UUID 防止盘符漂移 cp /etc/fstab /etc/fstab.bak DISK_UUID$(blkid -s UUID -o value /dev/vdb) if [ -z $DISK_UUID ]; then echo ERROR: /dev/vdb UUID not found else # 追加到 fstab echo UUID${DISK_UUID} /data ext4 defaults,nofail 0 0 /etc/fstab # 校验并挂载 mount -a echo Mount successful. Current disk status: df -Th /data fi3. 安装依赖与 OpenVikingyum install -y curl git tree # 第 1 步安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 第 2 步配置环境变量 echo source $HOME/.cargo/env ~/.bashrc source ~/.bashrc # 验证安装 uv --version # 第 3 步在数据盘上创建虚拟环境 cd /data uv venv ovenv --python 3.11 # 第 4 步激活虚拟环境 source /data/ovenv/bin/activate # 第 5 步验证 echo Ready echo Python path: $(which python) echo Python version: $(python --version)在已激活的虚拟环境中安装 OpenVikinguv tool install openviking --upgrade4. 服务端配置与启动准备配置文件# 创建配置目录 mkdir -p ~/.openviking # 创建并编辑配置文件 vim ~/.openviking/ov.conf配置模板{ embedding: { dense: { api_base : api-endpoint, // e.g., https://ark.cn-beijing.volces.com/api/v3 api_key : your-api-key, // Model service API Key provider : provider-type, // volcengine or openai dimension: 1024, // Vector dimension model : model-name, // e.g., doubao-embedding-vision-251215 input : multimodal // Use multimodal for doubao-embedding-vision models } }, vlm: { api_base : api-endpoint, api_key : your-api-key, provider : provider-type, max_retries: 2, model : model-name // e.g., doubao-seed-2-0-lite-260428 or gpt-4-vision-preview } }提示在 vim 中按i进入插入模式粘贴配置然后按Esc输入:wq保存退出。各字段的深层含义可参考 01-configuration.mdembedding.dense.dimension必须与模型实际输出维度一致如豆包视觉向量模型为 1024input: multimodal允许对文本、图片及混合内容做向量化图像检索必须使用该模式vlm.max_retries仅对 429、5xx、超时等瞬时错误生效重试采用带抖动的指数退避0.5s 起、8s 封顶。后台启动服务source /data/ovenv/bin/activate mkdir -p /data/log/ nohup openviking-server /data/log/openviking.log 21 # 注意数据将存储在相对执行路径的 ./data 目录下 # 停止服务pkill openviking; pkill agfs注意生产环境如需故障自动重启建议使用systemctl托管本指南不展开可参考 03-deployment.md 中的 systemd 单元文件示例。验证服务状态# 检查进程 ps aux | grep openviking-server # 查看日志 tail -f /data/log/openviking.log5. 客户端配置与测试CLI确保本机也安装了openviking以使用 CLI并将ovcli.conf指向你的服务器地址。vim ~/.openviking/ovcli.conf写入以下内容替换为服务器 IP{ url: http://XXX.XXX.XXX.XXX:1933, api_key: your-key }监控系统健康openviking observer system功能测试上传与检索# 上传测试资源 openviking add-resource https://raw.githubusercontent.com/ZaynJarvis/doc-eval/refs/heads/main/text.md # 列出资源 openviking ls viking://resources # 测试检索 openviking find who is Alice八、安全与生产化要点认证必配默认host为127.0.0.1。一旦将服务暴露到网络上必须配置root_api_keyserver.root_api_key否则服务会拒绝启动server.auth_mode未显式配置时设置了root_api_key会自动进入api_key模式未设置则进入仅限本机的dev模式详见 04-authentication.md。健康检查/health为存活探针Liveness/ready为就绪探针Readiness会检查 AGFS、VectorDB、APIKeyManager、Embedding、Ollama分别对应 K8s 的两种探针场景详见 03-deployment.md。进程管理ECS 场景使用nohup后台运行生产环境推荐 systemd 托管实现开机自启与崩溃自动重启。下一步Server Deployment - 配置、认证与部署选项全解API Overview - 完整 API 参考Authentication - 使用 API Key 保护你的服务端【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考