OpenViking 快速上手5 分钟搭建 AI Agent 语义上下文数据库【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking导读本文是 OpenViking 的官方快速入门指南面向希望在本地快速体验统一 Agent 记忆、知识 RAG 与技能能力的开发者。通过本文你将掌握两种安装方式Python 包与 Docker、模型服务配置VLM Embedding、服务端初始化与健康检查以及使用官方 Python SDK 完成添加资源 → 语义检索 → 读取摘要的完整链路从而为后续深入使用 Agent 记忆、上下文编译等功能打好基础。环境前置要求在开始之前请确认你的环境满足以下条件项目要求Python 版本3.10 或更高操作系统Linux、macOS、Windows网络连接需要稳定的网络用于下载依赖以及访问模型服务OpenViking 的架构决定了它至少需要两类模型能力这也是后续配置的核心VLM 模型视觉语言模型用于图片与内容的语义理解负责生成资源的 L0 摘要Abstract与 L1 概览OverviewEmbedding 模型用于向量化与语义检索是find()等语义搜索能力的基础。安装与启动两种方式OpenViking 既可以通过 Python 包作为本地库使用也可以通过 Docker 快速启动为独立服务两种方式二选一即可。方式一以 Python 包方式安装根据你的偏好选择包管理器官方推荐优先使用 uvuv tool install openviking --upgradepip install openviking --upgrade --force-reinstall# 安装 pipx install openviking # 更新 pipx upgrade openviking安装完成后你将获得两个命令ov作为客户端命令openviking是它的别名openviking-server作为服务端命令。方式二通过 Docker 启动独立服务如果你希望以独立服务方式运行 OpenViking推荐使用 Docker。第 1 步准备配置目录在宿主机上创建 OpenViking 目录并准备ov.conf配置文件。所有持久化状态——包括配置和 workspace 数据——都保存在这一个目录下mkdir -p ~/.openviking touch ~/.openviking/ov.conf第 2 步使用 Docker Compose 启动创建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默认情况下容器会在1933端口启动 OpenViking API 服务同时通过/studio提供 Web Studio UI以及内置的vikingbot网关。如果不需要vikingbot可追加command: [--without-bot]或在环境变量中设置OPENVIKING_WITH_BOT0。关于 bind mount 不可用的平台在部分不允许 bind mount 的托管平台上如 Railway、Fly.io 等 PaaS可以通过OPENVIKING_CONF_CONTENT环境变量传入完整的配置 JSON让容器在首次启动时自动引导也可以在容器启动后通过docker exec进入并执行openviking-server init。相关细节参见 Deployment Guide。当ov.conf不存在时容器入口脚本并不会崩溃而是打印修复提示并等待配置文件出现一旦文件就绪即自动继续启动服务见 03-deployment.md 源码描述。Mac 本地网络访问提示Connection reset 错误出于安全考虑OpenViking 默认只监听127.0.0.1。如果你在 Mac 上使用 Docker宿主机可能无法直接通过localhost:1933访问容器。推荐方案使用 socat 做端口转发无需修改配置在docker-compose.yml中覆盖默认启动命令用 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这一方案可完美解决 Mac 宿主机的访问问题。模型准备VLM 与 EmbeddingOpenViking 对模型服务的支持较为宽泛当前仓库支持以下来源火山引擎豆包系列模型官方推荐性价比高、性能良好新用户有免费额度。购买与开通流程参见 Volcengine 购买指南OpenAI 模型支持 GPT 系列 VLM 模型与 OpenAI Embedding 模型OpenAI Codex通过 ChatGPT/Codex OAuth 将 Codex 作为 VLM 提供方其他自定义模型服务任何兼容 OpenAI API 格式的模型服务均可接入。从仓库根目录的 examples/ov.conf.example 可以看到更完整的支持矩阵Embedding 侧还支持azure、vikingdb、jina、ollama、gemini、voyage、dashscope、minimax、cohere、litellm、local等 providerVLM 侧还支持kimiKimi Coding 订阅与glm智谱 GLM Coding Plan等。配置初始化向导与手动配置推荐的首启流程官方强烈建议首次使用通过初始化向导完成配置openviking-server init openviking-server doctor从源码看openviking-server init对应 openviking_cli/setup_wizard.py 中的向导入口它会分别提示你配置 Embedding 与 VLM若选择OpenAI Codex向导还能直接帮你导入已有 Codex 认证或引导登录。openviking-server doctor则对应 openviking_cli/doctor.py用于校验本地配置、模型连通性与认证状态是启动前最有价值的自检步骤。手动创建 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取决于你选择的 VLM 服务部分 provider如openai-codex可能使用本地 OAuth 状态而非手动粘贴的 API Key此时vlm.api_key是可选的。各模型提供方的完整示例见 配置指南 - 配置示例。以仓库默认示例 examples/ov.conf.example 中的火山引擎配置为例{ embedding: { dense: { model: doubao-embedding-vision-251215, api_key: {your-api-key}, api_base: https://ark.cn-beijing.volces.com/api/v3, dimension: 1024, provider: volcengine, input: multimodal } }, vlm: { model: doubao-seed-2-0-lite-260428, api_key: {your-api-key}, api_base: https://ark.cn-beijing.volces.com/api/v3, temperature: 0.0, max_retries: 2, provider: volcengine } }配置要点依据 配置指南 与示例文件embedding.dense.dimension向量维度必须与所选模型匹配如doubao-embedding-vision-251215为 1024OpenAItext-embedding-3-small为 1536embedding.dense.inputtext或multimodal多模态模式支持图文混合向量化图像检索依赖该模式vlm.model用于 L0/L1 语义提取官方推荐doubao-seed-2-0-lite-260428若完全未配置 VLML0/L1 将由内容直接生成语义较弱多模态资源的描述也可能受限。环境变量当配置文件位于默认路径~/.openviking/ov.conf时无需额外设置OpenViking 会自动加载。若配置文件在其他位置通过环境变量指定export OPENVIKING_CONFIG_FILE/path/to/your/ov.conf从 openviking/server/bootstrap.py 的实现看--config命令行参数最终也是通过设置OPENVIKING_CONFIG_FILE环境变量让配置单例从指定文件加载的因此命令行与环境变量两种方式底层是同一套机制。启动本地服务首次本地运行时初始化配置并启动服务openviking-server init openviking-server保持服务端运行另开一个终端执行下面的 Python SDK 示例。若要使用自定义配置路径可用openviking-server --config /path/to/ov.conf启动。默认本地部署不需要 API Key如果需要启用认证的服务器请在运行示例前设置OPENVIKING_API_KEY。启动后可执行curl http://localhost:1933/health验证服务状态正常会返回{status: ok}参见 部署指南。运行第一个示例创建 Python 脚本创建example.pyfrom openviking_sdk import SyncHTTPClient # 连接本地 OpenViking Server client SyncHTTPClient(urlhttp://localhost:1933) try: # 检查连接 client.initialize() # 添加资源支持 URL、文件或目录 # 本地目录扫描默认遵循 .gitignore。 # 等待语义处理完成后再查看资源。 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] # 查看资源树结构 ls_result client.ls(uriroot_uri) print(fDirectory structure:\n{ls_result}\n) # 使用 glob 查找 markdown 文件 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) # 获取资源的摘要与概览 abstract client.abstract(uriroot_uri) overview client.overview(uriroot_uri) print(fAbstract:\n{abstract}\n\nOverview:\n{overview}\n) # 执行语义搜索 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})) # 关闭客户端 client.close() except Exception as e: print(fError: {e})这个脚本与仓库中的官方示例 examples/quick_start.py 完全一致可以直接作为模板使用。SDK 实现位于 sdk/python/openviking_sdk/client.pySyncHTTPClient是异步客户端的同步封装每个方法底层对应一个 HTTP 接口SDK 方法底层接口说明initialize()会话建立 身份头注入检查连接携带X-API-Key等认证头见 client.pyadd_resource(path, waitTrue)资源导入支持 URL、本地文件或目录waitTrue会阻塞直到语义处理完成见 client.pyls(uri)/api/v1/...资源树列举查看资源树结构glob(pattern, uri)资源树匹配按 glob 模式查找节点见 client.pyread(uri, offset, limit)/api/v1/content/read读取文件内容支持偏移量与长度见 client.pyabstract(uri)/api/v1/content/abstract获取资源 L0 摘要见 client.pyoverview(uri)/api/v1/content/overview获取资源 L1 概览见 client.pyfind(query, target_uri)语义检索返回带相似度分数的资源列表见 client.py运行脚本python example.py预期输出Wait for semantic processing... Directory structure: ... Content preview: ... Abstract: ... Overview: ... Search results: viking://resources/... (score: 0.8523) ...至此你已经成功运行了 OpenViking 的完整链路资源摄入add_resource→ 结构探索ls/glob→ 内容读取read→ 语义摘要abstract/overview→ 语义检索find。返回结果中的viking://resources/...是资源在 OpenViking 命名空间中的统一资源标识符URI。下一步服务端模式如需将 OpenViking 作为共享服务运行参见 Quick Start: Server Mode深入配置完整的配置项说明与各模型 provider 示例见 Configuration GuideAPI 参考整体接口设计见 API Overview资源管理相关接口见 Resource Management部署细节systemd 服务、Docker 无 bind mount 平台引导、多实例部署等见 Deployment Guide。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考