OpenViking 快速开始：5 分钟搭建 Agent 上下文数据库并跑通首个语义检索示例

OpenViking 快速开始5 分钟搭建 Agent 上下文数据库并跑通首个语义检索示例【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本文是 OpenViking 的快速上手指南围绕官方快速开始文档展开覆盖 Python 包 / Docker 两种安装方式、Embedding 与 VLM 模型准备、ov.conf配置、本地服务启动以及用 Python SDK 完成「添加资源 → 查看目录树 → 语义检索」的首个完整示例。读完本文你将能够在本机独立部署一个可用的 OpenViking 服务并掌握SyncHTTPClient的核心调用链为后续接入 Agent 记忆、RAG 与技能库打好基础。前置要求在开始之前请确认你的环境满足以下条件Python 版本3.10 或更高版本SDK 侧要求见 sdk/python/README_CN.md操作系统Linux、macOS、Windows 均可网络连接需要稳定的网络连接用于下载依赖包和访问模型服务若使用provider volcengine火山方舟 / Ark runtime当前建议优先使用 Python 3.13 及以下版本运行openviking-server详见 快速开始服务端模式。安装与启动两种方式任选OpenViking 支持两种部署形态作为本地库同时提供ov客户端命令与服务端命令或通过 Docker 以独立服务方式运行。方式一通过 Python 包安装本地命令与库选择你常用的 Python 包管理工具安装# uv推荐 uv tool install openviking --upgrade # pip pip install openviking --upgrade --force-reinstall # pipx pipx install openviking pipx upgrade openviking安装完成后你将获得两个入口命令ovopenviking是其别名客户端命令用于连接远程服务端执行资源管理与检索openviking-server服务端命令负责初始化、体检与启动本地服务。轻量场景下还可以只安装openviking-sdkPyPI 包名openviking-sdk导入名openviking_sdk它不包含本地运行时、服务端和 CLI 依赖仅提供AsyncHTTPClient/SyncHTTPClient用于调用已有服务见 sdk/python/README_CN.md。方式二通过 Docker 启动独立服务如果你想将 OpenViking 作为独立服务运行推荐使用 Docker所有持久化状态配置 工作区数据都收拢在宿主机的一个目录下mkdir -p ~/.openviking touch ~/.openviking/ov.conf创建docker-compose.ymlservices: openviking: image: ghcr.io/volcengine/openviking:latest container_name: openviking ports: - 1933:1933 volumes: - ~/.openviking:/app/.openviking restart: unless-stopped启动docker-compose up -d容器默认会启动 OpenViking API 服务端口1933同时在/studio提供 Web Studio 前端以及内置的vikingbotgateway。如需关闭vikingbot可在 Compose 中增加command: [--without-bot]或设置环境变量OPENVIKING_WITH_BOT0。如果运行平台不支持 bind mount可以通过OPENVIKING_CONF_CONTENT环境变量传入完整的配置 JSON或在容器启动后docker exec进入容器执行openviking-server init详见 部署指南。Mac 本地网络访问提示Connection reset 报错出于安全考虑OpenViking 默认仅监听127.0.0.1。在 Mac 上使用 Docker 时宿主机可能无法直接通过localhost:1933访问。推荐用 socat 在容器内部做端口转发无需修改配置services: openviking: image: ghcr.io/volcengine/openviking:latest ports: - 1933:1934 # 将宿主机 1933 映射到容器 1934 volumes: - ~/.openviking:/app/.openviking command: /bin/sh -c apt-get update apt-get install -y socat socat TCP-LISTEN:1934,fork,reuseaddr TCP:127.0.0.1:1933 openviking-server模型准备VLM Embedding 缺一不可OpenViking 作为「自进化上下文数据库」其语义能力依赖两类模型VLM 模型用于图像和内容理解承担语义提取L0/L1 生成Embedding 模型用于向量化和语义检索。支持的模型服务包括模型服务说明火山引擎豆包模型官方推荐成本低、性能好新用户有免费额度购买与开通见 火山引擎购买指南OpenAI 模型支持 GPT-4V 等 VLM 模型和 OpenAI Embedding 模型OpenAI Codex通过 ChatGPT/Codex OAuth 使用 Codex 作为 VLM其他自定义模型服务支持兼容 OpenAI API 格式的模型服务配置指南中提供了更多 provider如kimi、glm、litellm等完整列表见 配置指南。配置环境初始化向导与 ov.conf推荐使用初始化向导openviking-server init openviking-server doctoropenviking-server init会引导你选择 provider 并生成可直接使用的配置模板对于 OpenAI、Volcengine、Kimi、GLM 这类 API 型 VLM按提示填写对应 API Key若选择OpenAI Codex向导会自动导入已有的 Codex 鉴权或引导登录。openviking-server doctor则校验当前本地配置是否可用包括各 provider 需要的鉴权状态。手动创建 ov.conf配置文件默认放在~/.openviking/ov.conf。最小可用的模板如下{ embedding: { dense: { api_base : api-endpoint, api_key : your-api-key, provider : provider-type, dimension: 1024, model : model-name } }, vlm: { api_base : api-endpoint, api_key : your-api-key, provider : provider-type, model : model-name } }provider、model、api_base和api_key取决于你选择的模型服务部分 provider 可能使用本地 OAuth 状态而非手动填写的 API Key例如provider为openai-codex且 Codex OAuth 已就绪时vlm.api_key可以省略。各模型服务的完整配置示例火山引擎豆包、OpenAI、Codex、Kimi、GLM 等参见 配置指南 - 配置示例。设置环境变量配置文件放在默认路径~/.openviking/ov.conf时无需任何设置OpenViking 会自动加载。放在其他位置时通过环境变量指定export OPENVIKING_CONFIG_FILE/path/to/your/ov.conf注意服务端只在进程启动时读取ov.conf不会监听文件变化修改embedding、vlm、rerank、retrieval、storage或server配置后需要重启服务并建议重启后再次运行openviking-server doctor验证见 配置指南 - 配置重载边界。启动本地服务首次本地运行完成初始化后直接启动openviking-server init openviking-server保持服务运行然后在另一个终端执行 Python SDK 示例。如果使用了自定义配置路径用--config指定openviking-server --config /path/to/ov.conf默认本地模式不需要 API Key如果连接的是启用了鉴权的 Server需要先设置OPENVIKING_API_KEY环境变量或直接在客户端构造时传入api_key。启动成功后可看到类似INFO: Uvicorn running on http://0.0.0.0:1933的日志并可用curl http://localhost:1933/health验证返回{status: ok}。运行第一个示例添加资源并语义检索创建 Python 脚本创建example.pyfrom openviking_sdk import SyncHTTPClient # 连接本地 OpenViking Server client SyncHTTPClient(urlhttp://localhost:1933) try: # 检查连接 client.initialize() # Add resource (supports URL, file, or directory) # Local directory scans respect .gitignore by default. # Wait until semantic processing completes before inspecting the resource. print(Wait for semantic processing...) add_result client.add_resource( pathhttps://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md, waitTrue, ) root_uri add_result[root_uri] # Explore the resource tree structure ls_result client.ls(uriroot_uri) print(fDirectory structure:\n{ls_result}\n) # Use glob to find markdown files glob_result client.glob(pattern**/*.md, uriroot_uri) if glob_result[matches]: content client.read(uriglob_result[matches][0]) print(fContent preview: {content[:200]}...\n) # Get abstract and overview of the resource abstract client.abstract(uriroot_uri) overview client.overview(uriroot_uri) print(fAbstract:\n{abstract}\n\nOverview:\n{overview}\n) # Perform semantic search results client.find( querywhat is openviking, target_uriroot_uri, ) print(Search results:) for result in results.get(resources, []): print(f {result[uri]} (score: {result.get(score, 0.0):.4f})) # Close the client client.close() except Exception as e: print(fError: {e})运行脚本python example.py预期输出Wait for semantic processing... Directory structure: ... Content preview: ... Abstract: ... Overview: ... Search results: viking://resources/... (score: 0.8523) ...恭喜你已成功运行 OpenViking。底层实现解读SDK 调用链与语义管线上面的脚本背后对应的是 sdk/python/openviking_sdk/client.py 中SyncHTTPClient的一组方法类定义见 client.py L2199-L2218它们各自包装了异步实现并映射到对应的 HTTP APIinitialize()建立连接并检查服务可达性add_resource(path, waitTrue)向POST /api/v1/resources发起请求。当path指向本地文件或目录时SDK 会先将其打包上传目录会被压缩为 zip 后走临时上传URL 则直接放入请求体见 client.py L715-L772。waitTrue会等待语义处理完成后再返回root_urils(uri)/glob(pattern, uri)浏览资源树结构GET /api/v1/fs/ls与按 glob 模式匹配文件read(uri)读取文件原文GET /api/v1/content/read支持offset/limitabstract(uri)/overview(uri)分别获取资源的 L0 摘要与 L1 概览对应GET /api/v1/content/abstract与/api/v1/content/overviewfind(query, target_uri)执行语义检索POST /api/v1/search/find返回带score的结果列表close()释放底层 HTTP 连接。关于语义管线的原理添加资源时VLM 会为资源生成L0摘要——约 100 token 的精炼总结以及L1概览——约 2k token、包含导航信息的结构化描述L2 则是内容本身按语义切分的块。未配置 VLM 时L0/L1 会直接从内容生成语义性较弱多模态资源描述可能有限详见 配置指南 - vlm。向量化环节由 Embedding 模型完成dimension必须与模型输出维度一致否则会出现Vector dimension mismatch错误。find返回的score默认即语义相似度如果你想对高频访问或最近更新的上下文做排序提升可以配置retrieval.hotness_alpha见 配置指南 - retrieval默认0.0表示分数严格反映向量相似度。进阶以客户端方式连接远程服务快速开始文档的结尾指向了服务端模式。当你需要将 OpenViking 作为共享服务运行时可参考 快速开始服务端模式它涵盖启动服务openviking-server doctor先做本地校验再以openviking-server/--port 1933等方式启动Python SDK 连接import openviking as ov; ov.SyncHTTPClient(urlhttp://localhost:1933)服务端启用鉴权后按场景传入user_key/admin_key数据访问或root_key仅管理操作CLI 连接编写~/.openviking/ovcli.conf含url与api_key随后直接使用openviking observer system、openviking add-resource url、openviking ls viking://resources、openviking find query等命令curl 连接远端 URL 可直接放入path本地文件需先调用POST /api/v1/resources/temp_upload上传再用返回的temp_file_id调目标 API云端部署火山引擎 ECS veLinux 的完整部署流程数据盘挂载、uv 安装、虚拟环境、后台常驻与日志查看。下一步配置详解 - 详细配置选项Embedding、VLM、Rerank、存储、加密、Server 段等API 概览 - API 参考资源管理 - 资源管理 API快速开始服务端模式 - 将 OpenViking 作为共享 HTTP 服务运行至此你已经走通了 OpenViking 从安装、配置到首个语义检索示例的完整流程。接下来可以在此基础上接入你自己的文档、代码目录或 Agent 会话数据逐步构建属于你的上下文数据库。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考