在 Kubernetes 上部署 OpenViking：基于 Helm Chart 的 RAG 语义搜索服务实战指南

在 Kubernetes 上部署 OpenViking：基于 Helm Chart 的 RAG 语义搜索服务实战指南

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

OpenViking 是一个开源的 RAG（检索增强生成）与语义搜索引擎，同时以上下文数据库 MCP（Model Context Protocol）服务器的形态为 AI Agent 提供统一的记忆、知识与技能检索能力。本指南围绕 examples/k8s-helm/README.md 与仓库内实际的 Helm Chart 模板展开，系统讲解如何将 OpenViking 部署到 Kubernetes 集群：从前置条件、Helm 安装、核心配置项（Embedding / VLM / 云厂商适配）到存储、安全、自动扩缩容、客户端接入与故障排查。读完本文，你将具备在生产集群上用 Helm 一键拉起、配置并验证 OpenViking 服务的能力，并能结合源码理解其配置下发与健康检查的底层机制。

一、OpenViking 与 Helm Chart 的定位

OpenViking 作为「Self-evolving Context Database for AI Agents」，核心能力是统一 Agent Memory、Knowledge RAG 与 Skills，对外以 MCP 服务器形式暴露上下文数据库能力。将其部署到 Kubernetes 的价值在于：利用 K8s 的弹性伸缩、服务发现与滚动更新能力，将 RAG/语义搜索服务做成生产可用的常驻服务。

仓库中存在两套 Helm Chart：

• examples/k8s-helm（本文主体）：包含 Chart.yaml、values.yaml 以及templates/下的 deployment.yaml、secret.yaml、service.yaml、_helpers.tpl、NOTES.txt，是「配置即 Secret、以 uv 运行时拉起服务」的极简形态；
• deploy/helm/openviking：更完整的发行版 Chart，额外包含 configmap.yaml、ingress.yaml、pvc.yaml、serviceaccount.yaml，适合生产发布场景。

从 Chart.yaml 的元数据可以看出该 Chart 的定位：type: application，关键词涵盖rag、semantic-search、mcp、knowledge-base，即「面向知识库的 RAG + 语义搜索 + MCP 上下文数据库」。

二、前置条件

根据文档，部署前需要准备：

• Kubernetes 1.24+：保证 HPA、PVC、Secret 等资源的 API 版本可用；
• Helm 3.8+：Chart 基于 Helm v2（apiVersion: v2）编写，需使用 Helm 3 的命令行体系；
• 有效的火山引擎（Volcengine）API Key：用于 Embedding 与 VLM 两类模型服务的调用鉴权，对应openviking.config.embedding.dense.api_key与openviking.config.vlm.api_key。

此外，从 values.yaml 可以看到默认模型与接入点：

三、安装 Chart

3.1 添加 Helm 仓库（发布后可用）

文档给出了仓库形态的安装方式（注意：该仓库当前以源码形式发布，发布后可执行）：

helm repo add openviking https://volcengine.github.io/openviking helm repo update

3.2 从本地 Chart 安装

在当前仓库中，Chart 源码位于examples/k8s-helm（发行版位于deploy/helm/openviking），可直接从本地目录安装：

# 使用默认值安装 helm install openviking ./examples/k8s-helm # 使用自定义 values 文件安装 helm install openviking ./examples/k8s-helm -f my-values.yaml # 使用 --set 覆盖单个参数安装 helm install openviking ./examples/k8s-helm \ --set openviking.config.embedding.dense.api_key=YOUR_API_KEY

安装完成后，NOTES.txt 会提示如何访问服务：

kubectl port-forward svc/openviking 1933:1933 -n <namespace> curl http://localhost:1933/health

3.3 快速开始（云厂商参数）

文档给出的快速开始命令同时设置了cloudProvider与 Embedding API Key：

# GCP 部署 helm install openviking ./openviking \ --set cloudProvider=gcp \ --set openviking.config.embedding.dense.api_key=YOUR_API_KEY # AWS 部署 helm install openviking ./openviking \ --set cloudProvider=aws \ --set openviking.config.embedding.dense.api_key=YOUR_API_KEY

需要说明：cloudProvider、autoscaling、dataVolume、existingSecret等参数在文档中均有描述，但当前 examples/k8s-helm/values.yaml 只实际声明了image、service、resources、server、openviking.config五个顶层字段。因此上述「快速开始」中的参数属于文档规划的能力；若需完整的多云注解、Ingress、PVC 能力，请参考功能更完整的 deploy/helm/openviking/values.yaml（含 ingress、pvc、serviceaccount 等模板）。

四、核心配置详解

4.1 关键参数一览

文档整理了以下参数表（实际默认值以 values.yaml 为准，下表对两处不一致做了标注）：

4.2 OpenViking 配置的下发机制（源码级）

文档强调：ov.conf中的所有 OpenViking 配置选项都可以放在openviking.config下。其底层实现非常巧妙，见 secret.yaml：

apiVersion: v1 kind: Secret metadata: name: {{ include "openviking.fullname" . }}-config type: Opaque stringData: ov.conf: | {{ toJson .Values.openviking.config | indent 4 }}

也就是说，Helm 在渲染阶段会把values.yaml中openviking.config子树整体序列化为 JSON，并作为名为ov.conf的键写入一个 Opaque Secret。随后 deployment.yaml 将该 Secret 以只读卷的形式挂载到/etc/openviking/ov.conf：

volumeMounts: - name: config mountPath: /etc/openviking readOnly: true volumes: - name: config secret: secretName: {{ include "openviking.fullname" . }}-config

容器启动命令通过uv run动态拉取并执行 OpenViking 服务，同时显式指定配置路径：

exec uv run --with openviking openviking-server \ --host 0.0.0.0 \ --port 1933 \ --config /etc/openviking/ov.conf

从源码结构看，这种「Secret 挂载 + 显式 --config 参数」的设计有两点收益：其一，API Key 等敏感信息不会明文进入 ConfigMap 或 Pod Spec 的注解，天然满足生产密钥管理诉求；其二，deployment 模板中带有一行checksum/config: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}注解，配置内容一旦变化，checksum 随之变化，会触发 Pod 滚动更新，保证配置变更即时生效。

4.3 Embedding 配置

Embedding 服务需要火山引擎 API Key，完整配置片段：

openviking: config: embedding: dense: api_key: "your-api-key-here" api_base: "https://ark.cn-beijing.volces.com/api/v3" model: "doubao-embedding-vision-251215"

values.yaml 中还有两个文档未展开但同样会传入ov.conf的字段：dimension: "1024"（向量维度）与backend: "volcengine"（模型服务后端），部署时可一并按需覆盖。

4.4 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"

五、存储方案

5.1 默认 emptyDir（仅开发/测试）

当前 examples Chart 的 Deployment 模板中未声明持久化卷，数据落在 Pod 的临时存储上，Pod 重启即丢失。文档明确警告：emptyDir 仅适用于开发与测试。

5.2 持久化存储（可选）

文档给出的 PVC 启用方式（该参数由更完整的 Chart 提供）：

openviking: dataVolume: enabled: true usePVC: true size: 50Gi storageClassName: standard accessModes: - ReadWriteOnce

对应到发行版 Chart，PVC 声明位于 deploy/helm/openviking/templates/pvc.yaml，可通过storageClassName对接云厂商的托管存储卷，避免 Pod 重建导致索引数据丢失。

六、安全加固

6.1 服务端 API Key 认证

为保护 OpenViking 服务端，可在openviking.config.server下开启鉴权并配置 CORS 白名单：

openviking: config: server: api_key: "your-secure-api-key" cors_origins: - "https://your-domain.com"

6.2 密钥管理

生产环境建议使用 Kubernetes Secrets 或外部密钥管理，避免密钥出现在 values 文件与 Helm Release 记录中：

# 从字面值创建 Secret kubectl create secret generic openviking-config \ --from-literal=ov.conf='{"server":{"api_key":"secret"}}' # 或挂载现有 Secret helm install openviking ./openviking \ --set existingSecret=openviking-config

配合前文介绍的「Secret 挂载机制」，可以将 API Key 与集群内已存在的 Secret 解耦管理。

七、自动扩缩容与资源限制

7.1 Horizontal Pod Autoscaler

面向生产工作负载，文档建议启用 HPA：

autoscaling: enabled: true minReplicas: 2 maxReplicas: 10 targetCPUUtilizationPercentage: 80 targetMemoryUtilizationPercentage: 80

7.2 资源限制

文档给出的默认资源配置如下：

resources: limits: cpu: 2000m memory: 4Gi requests: cpu: 500m memory: 1Gi

需要再次提醒：examples Chart 的 values.yaml 实际默认值是limits: cpu 1000m / memory 2Gi、requests: cpu 200m / memory 512Mi。向量化与 RAG 服务的资源占用与文档库规模强相关，请根据实际 workload 调整，并在 HPA 中为 CPU/内存留出合理余量。

八、服务验证与客户端接入

8.1 获取访问端点

# 若 Service 为 LoadBalancer，取负载均衡器 IP export OPENVIKING_IP=$(kubectl get svc openviking -o jsonpath='{.status.loadBalancer.ingress[0].ip}') # 若 Service 为 ClusterIP，可用 port-forward 暴露到本地 kubectl port-forward svc/openviking 1933:1933

8.2 使用 ovcli CLI 连接

OpenViking 的命令行工具通过~/.openviking/ovcli.conf读取服务地址与鉴权信息：

cat > ~/.openviking/ovcli.conf <<EOF { "url": "http://$OPENVIKING_IP:1933", "api_key": null, "output": "table" } EOF # 测试连接 openviking health

8.3 使用 Python SDK

文档提供了完整的 Python 客户端接入示例，使用openviking_sdk.SyncHTTPClient：

from openviking_sdk import SyncHTTPClient # 获取服务端点 # kubectl get svc openviking client = SyncHTTPClient(url="http://<load-balancer-ip>:1933", api_key="your-key") client.initialize() # 添加资源 client.add_resource(path="./document.pdf") client.wait_processed() # 搜索 results = client.find("your search query") print(results) client.close()

典型调用链路为：initialize()建立会话 →add_resource()注入文档资源 →wait_processed()等待解析与向量化完成 →find()执行语义检索。对应 SDK 的完整能力可参考 sdk/python 与 openviking/client。

8.4 健康检查端点

从 deployment.yaml 可以看到 Chart 内置了两类探针：

• livenessProbe：GET/health，initialDelaySeconds: 120、periodSeconds: 15、failureThreshold: 5；
• readinessProbe：GET/ready，initialDelaySeconds: 60、periodSeconds: 10、failureThreshold: 5。

首次启动需要拉取依赖并加载模型配置，因此探针的initialDelaySeconds设置得较宽容（120 秒），避免启动阶段被误判为不健康而被反复重启。

九、故障排查

十、卸载

helm uninstall openviking

如需一并清理持久化数据（启用了 PVC 时）：

kubectl delete pvc openviking-data

注意：Helm 卸载默认不会删除 PVC，生产环境清理前请先确认索引数据是否需要保留。

十一、小结：从 Chart 到生产可用的关键点

基于本文与仓库源码，可以提炼出在 Kubernetes 上运行 OpenViking 的几条实践要点：

1. 配置即代码：openviking.config子树会被整体序列化为ov.conf存入 Secret 并挂载到/etc/openviking/ov.conf（见 secret.yaml），服务端通过--config显式读取，配置变更会经 checksum 注解自动触发滚动更新；
2. 密钥隔离：Embedding / VLM 的火山引擎 API Key 与服务端 API Key 都应优先走 Kubernetes Secret，避免进入 values 文件；
3. 存储与弹性：生产环境务必启用 PVC（参考 deploy/helm/openviking/templates/pvc.yaml）并配置 HPA 与合理的资源请求/限制；
4. 验证链路：以/health、/ready探针 + ovcli 的openviking health+ Python SDK 的add_resource → wait_processed → find三段式完成端到端验证。

如果你需要进一步的 Ingress 域名暴露、ServiceAccount 鉴权或多云注解能力，可直接以 deploy/helm/openviking 为基线进行二次定制。

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking