使用 Helm 在 Kubernetes 上部署 OpenVikingRAG 与语义搜索服务的生产级实践指南【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking导读本文以 OpenViking 官方提供的 examples/k8s-helm Helm Chart 为主体系统讲解如何在 Kubernetes 集群上部署 OpenViking——一个面向 AI Agent 的自进化上下文数据库统一提供 Agent 记忆、知识库 RAG 与技能Skills能力并以 MCPModel Context Protocol服务器形态对外提供语义搜索服务。读完本文你将掌握 Chart 的目录结构、配置参数Embedding / VLM / 认证 / 存储 / 资源、安装与卸载命令、CLI 与 Python 客户端连接方式以及基于仓库源码的底层实现原理与故障排查思路。OpenViking 与 Helm Chart 定位OpenViking 是开源的 RAG 与语义搜索引擎作为上下文数据库 MCP 服务器运行。它通过openviking-server进程对外提供 HTTP 服务默认端口 1933支持将本地文档解析、向量化后写入向量数据库并提供语义检索能力同时可作为 Agent 的记忆与技能统一入口。Helm ChartChart 名openviking版本0.1.0的目标是让这一能力在 Kubernetes 上一键部署、开箱即用兼容主流云服务商环境。Chart 的全部清单文件位于 examples/k8s-helm/templates包括文件作用Chart.yamlChart 元数据名称、版本、关键词rag / semantic-search / mcp / knowledge-basevalues.yaml全部可配置参数及默认值templates/deployment.yamlDeployment 工作负载定义含启动命令与探针templates/secret.yaml以 Kubernetes Secret 形式承载ov.conf配置templates/service.yamlService 暴露定义templates/_helpers.tplChart 命名与标签模板templates/NOTES.txt安装后提示信息端口转发、健康检查前置条件部署前请确认环境满足Kubernetes 1.24Helm 3.8有效的火山引擎 API Key用于 Embedding 和 VLM 服务此外由于默认镜像 ghcr.io/astral-sh/uv 的python3.12-bookworm标签以 uv 工具链为基础Pod 启动时会执行uv run --with openviking openviking-server见 templates/deployment.yaml动态安装并启动服务因此集群节点需要具备拉取镜像与访问 Python 包索引的网络能力。安装方式一添加 Helm 仓库发布后可用Chart 发布到官方 Helm 仓库后可执行helm repo add openviking https://volcengine.github.io/openviking helm repo update方式二从本地 Chart 安装Chart 源码位于当前仓库的examples/k8s-helm目录原 README 中的deploy/helm路径对应仓库旧版目录结构本仓库以examples/k8s-helm为准。使用默认值安装helm install openviking ./examples/k8s-helm使用自定义值文件安装helm install openviking ./examples/k8s-helm -f my-values.yaml快速开始以 GCP、AWS 为例通过--set直接指定云服务商与 API Key# GCP 部署 helm install openviking ./examples/k8s-helm \ --set cloudProvidergcp \ --set openviking.config.embedding.dense.api_keyYOUR_API_KEY # AWS 部署 helm install openviking ./examples/k8s-helm \ --set cloudProvideraws \ --set openviking.config.embedding.dense.api_keyYOUR_API_KEY安装完成后根据 templates/NOTES.txt 的提示可通过端口转发快速验证服务kubectl port-forward svc/openviking 1933:1933 -n namespace curl http://localhost:1933/health配置详解云服务商支持Chart 文档宣称支持为主流云服务商自动配置 LoadBalancer 注解配置值为云服务商配置值Google Cloud PlatformcloudProvider: gcpAmazon Web ServicescloudProvider: aws其他/通用cloudProvider: 默认需要说明的是从当前仓库的 templates/service.yaml 源码结构看Service 仅渲染type与端口映射尚未内置按cloudProvider分支注入注解的逻辑。若生产环境需要云服务商特定的负载均衡注解需在安装时通过--set service.annotations.keyvalue或自定义 values 文件补充或等待 Chart 后续版本实现。关键配置选项参数说明默认值cloudProvider云服务商用于 LoadBalancer 注解replicaCount副本数量1image.repository容器镜像仓库ghcr.io/astral-sh/uvimage.tag容器镜像标签python3.12-bookwormimage.pullPolicy镜像拉取策略IfNotPresentservice.typeKubernetes 服务类型ClusterIPREADME 示例写 LoadBalancer实际 values 为 ClusterIPservice.port服务端口1933server.host服务绑定地址0.0.0.0server.port服务监听端口1933openviking.config.embedding.dense.api_key火山引擎 Embedding API Keynullopenviking.config.vlm.api_key火山引擎 VLM API Keynull说明README 表格中service.type默认值写为LoadBalancer但仓库实际 values.yaml 的默认值为ClusterIP本文以实际 values 为准。如需对外暴露可通过--set service.typeLoadBalancer覆盖。OpenViking 配置注入机制ov.conf 的生成这是本 Chart 的核心实现细节。templates/secret.yaml 将values.yaml中openviking.config下的全部内容序列化为 JSON写入名为release-openviking-config的 Secret 的ov.conf键中stringData: ov.conf: | {{ toJson .Values.openviking.config | indent 4 }}而 templates/deployment.yaml 将该 Secret 以只读卷挂载到容器/etc/openviking目录启动命令随之指定--config /etc/openviking/ov.confexec uv run --with openviking openviking-server \ --host 0.0.0.0 \ --port 1933 \ --config /etc/openviking/ov.conf同时在 Pod 模板注解中写入配置的sha256sum校验和deployment.yaml当ov.conf内容发生变化时Helm 会自动触发滚动更新避免配置改了但 Pod 未重启的经典问题。从服务端看openviking-server的配置加载逻辑位于 openviking/server/app.py通过resolve_config_path解析--config路径并调用load_server_config完成加载。ov.conf的完整字段参考仓库根目录的 examples/ov.conf.example其中 server、storage、embedding、vlm 等均为合法顶层配置块。Embedding 配置OpenViking 的向量化依赖火山引擎 Embedding 服务需提供 API Keyopenviking: config: embedding: dense: api_key: your-api-key-here api_base: https://ark.cn-beijing.volces.com/api/v3 model: doubao-embedding-vision-251215Chart 默认值values.yaml还包含两个可选字段字段默认值说明dimension1024向量维度backendvolcengine向量化后端对照 examples/ov.conf.example 中的标准配置服务端还支持provider、input如multimodal、max_input_tokens、circuit_breaker等进阶参数需要更细粒度控制时可在openviking.config.embedding下追加。VLM 配置视觉语言模型VLM用于处理图片等多模态资源解析openviking: config: vlm: api_key: your-api-key-here api_base: https://ark.cn-beijing.volces.com/api/v3 model: doubao-seed-2-0-lite-260428同样可通过backend: volcengine指定后端见 values.yaml。存储默认emptyDir当前 Chart 的 Deployment 仅挂载配置卷未定义独立数据卷。README 文档描述了默认使用emptyDir卷的存储方案适合开发与测试但 Pod 重建或重新调度后数据将丢失。持久化存储可选README 提供了通过 PVC 启用持久化的配置示例适用于需要保留索引与记忆数据的生产场景openviking: dataVolume: enabled: true usePVC: true size: 50Gi storageClassName: standard accessModes: - ReadWriteOnce需要提醒以上dataVolume段为 README 文档描述的规划配置从当前 templates/deployment.yaml 源码结构看Chart 尚未内置对应的 PVC 模板与挂载逻辑。在生产使用持久化前请以本文所述的 Chart 实际文件为准可通过自定义 values 与扩展模板或额外创建 PVC 并在 Deployment 中挂载实现。若希望数据落盘到宿主节点可考虑将 OpenViking 服务端storage.workspace指向持久化路径其数据目录相关配置同样参考 examples/ov.conf.example 的storage块。安全API Key 认证为保护 OpenViking 服务器可启用服务端 API Key 认证与跨域白名单openviking: config: server: api_key: your-secure-api-key cors_origins: - https://your-domain.com这些键会被toJson序列化进ov.conf并随 Secret 挂载服务端按配置解析生效服务端默认配置示例使用root_api_key字段可参考 examples/ov.conf.example 的server块。密钥管理生产环境建议使用 Kubernetes Secrets 或外部密钥管理避免在 values 文件中明文存放密钥# 从字面值创建 Secret kubectl create secret generic openviking-config \ --from-literalov.conf{server:{api_key:secret}} # 或挂载现有 Secret helm install openviking ./examples/k8s-helm \ --set existingSecretopenviking-config注意当前 templates/secret.yaml 与 deployment.yaml 固定引用release-openviking-config这一 Secret 名称existingSecret参数尚未接入模板渲染逻辑属于文档规划能力实际使用时需以 Chart 当前实现为准自行确认 Secret 名称与挂载方式。自动扩缩容README 为生产工作负载提供了 Horizontal Pod AutoscalerHPA配置示例autoscaling: enabled: true minReplicas: 2 maxReplicas: 10 targetCPUUtilizationPercentage: 80 targetMemoryUtilizationPercentage: 80与存储类似当前 templates 目录未包含 HPA 清单autoscaling为文档规划配置。生产环境可基于该示例自行创建 HPA 资源或结合 templates/deployment.yaml 中的资源请求值设置合理的扩缩容阈值。资源限制README 给出的默认资源配置如下resources: limits: cpu: 2000m memory: 4Gi requests: cpu: 500m memory: 1Gi而仓库实际 values.yaml 中的默认值更精简CPU 限制 1000m / 内存 2Gi请求 200m / 512Mi。部署时请根据实际工作负载在 values 中调整resources.limits与resources.requests例如helm install openviking ./examples/k8s-helm \ --set resources.limits.cpu2000m \ --set resources.limits.memory4Gi合理设置资源请求可确保调度器为 Pod 预留足够容量同时为 HPA 提供度量基准。健康检查与就绪探针deployment.yaml 内置了两类探针探针路径初始延迟周期失败阈值livenessProbe/health120s15s5readinessProbe/ready60s10s5对应的服务端端点实现在 openviking/server/routers/system.pyGET /health用于存活探测GET /ready用于就绪探测。由于首次启动需要完成 Embedding / VLM 模型初始化与依赖安装探针初始延迟特意设置得较长120s / 60s避免启动阶段被误杀。使用示例使用 CLI 连接获取 LoadBalancer IP 并配置 ovcli# 获取 LoadBalancer IP export OPENVIKING_IP$(kubectl get svc openviking -o jsonpath{.status.loadBalancer.ingress[0].ip}) # 创建 CLI 配置 cat ~/.openviking/ovcli.conf EOF { url: http://$OPENVIKING_IP:1933, api_key: null, output: table } EOF # 测试连接 openviking healthovcli.conf的完整字段可参考仓库根目录的 examples/ovcli.conf.example支持api_key、root_api_key、timeout、output、extra_headers等配置。若 Service 类型为 ClusterIP可改用kubectl port-forward svc/openviking 1933:1933后连接http://localhost:1933。Python 客户端from openviking_sdk import SyncHTTPClient # 获取服务端点 # kubectl get svc openviking client SyncHTTPClient(urlhttp://load-balancer-ip:1933, api_keyyour-key) client.initialize() # 添加资源 client.add_resource(path./document.pdf) client.wait_processed() # 搜索 results client.find(your search query) print(results) client.close()上述流程对应 OpenViking 的资源入库 → 等待处理完成 → 语义检索标准用法add_resource触发文档解析与向量化wait_processed等待后台队列处理完成队列并发相关配置见 examples/ov.conf.example 的queue_workers块find执行向量检索并返回结果。故障排除Pod 启动失败检查 Pod 日志重点观察uv run安装依赖与服务启动输出kubectl logs -l app.kubernetes.io/nameopenviking若日志出现 API Key 缺失或模型调用失败优先检查openviking.config下的 Embedding / VLM 配置。健康检查失败验证实际下发到 Pod 的配置内容kubectl get secret openviking-config -o jsonpath{.data.ov\.conf} | base64 -d确认 JSON 合法且api_key已正确注入同时检查 Secret 名称是否与 deployment.yaml 中secretName引用一致模板渲染为release-openviking-config。LoadBalancer 未获取 IP等待云服务商完成负载均衡器分配kubectl get svc openviking -w若长时间无 IP检查 Service 类型是否已设置为LoadBalancer以及集群是否具备负载均衡器供应能力如云厂商 LB Controller / MetalLB。卸载helm uninstall openviking若启用了持久化存储PVC数据卷默认不会随 Helm 卸载自动删除需要显式清理kubectl delete pvc openviking-data小结本文以 examples/k8s-helm/README_CN.md 为骨架结合 values.yaml、templates/deployment.yaml、templates/secret.yaml 等清单文件与服务端 app.py 源码完整覆盖了 OpenViking 的 Helm 部署全流程从 Chart 结构、配置参数、配置注入原理到存储、安全、扩缩容、探针、客户端接入与故障排查。需要特别留意的是README 文档中描述的cloudProvider注解、dataVolumePVC、autoscalingHPA 与existingSecret等能力在当前 Chart 模板中尚未完全落地生产落地时应以仓库实际文件为准必要时自行扩展模板从而获得稳定、可持久化、可观测的生产级 RAG 与语义搜索服务。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考