chatqna-helm-deploy

ChatQnA Helm 部署

使用 Helm 将 Chat 问答核心示例应用 Helm chart 部署到 Kubernetes，chart 位于 sample-applications/chat-question-and-answer-core/chart/。该 chart 的依赖项为 chatqna-core 和 chatqna-ui，它们与 Docker Compose 部署使用相同的源代码构建。此外，chart 还包含 nginx，用作后端和 UI 的反向代理。

代码库根目录：sample-applications/chat-question-and-answer-core/

前置条件

1. 确认有可访问的 Kubernetes 集群，并且已配置 kubectl 以访问该集群。

     kubectl get nodes
   

2. For GPU, discover resource keys before writing values:

     kubectl get nodes -o json | jq -r '.items[] | "\(.metadata.name):\n" + (.status.allocatable | to_entries | map(select(.key | test("gpu|npu|vpu|accel";"i"))) | map("  \(.key): \(.value)") | join("\n"))'
   

   Common Intel keys are gpu.intel.com/i915, gpu.intel.com/xe

What This Skill Produces

• A running ChatQnA Core Helm release in a target namespace for one runtime:
  • OpenVINO CPU
  • OpenVINO GPU
  • Ollama
• A generated override file (values-override.yaml) that translates Docker Compose and setup_env.sh style inputs to Helm values keys.
• A verified deployment state using pods, services, and health endpoint checks.
• A concise deployment report containing:
  • runtime selected and GPU mode
  • chart source (local path or OCI chart)
  • values files used and major override keys
  • access URL and API docs URL
  • warnings (missing token, GPU key, model constraints)

When to Use

• "Deploy chatqna core to Kubernetes"
• "Helm install chatqna-core"
• "Configure values.yaml for chatqna core"
• "Translate docker compose setup_env.sh into helm values"
• "Deploy OpenVINO GPU profile with Helm"
• "Deploy Ollama with chart values"

Inputs To Confirm

Before running commands, confirm or infer these values:

1. Runtime: openvino or ollama
2. Device target: cpu or gpu (GPU valid only for OpenVINO)
3. Namespace and release name (default release: chatqna-core)
4. Chart source:
   • local chart path (./chart), or
   • OCI chart (oci://registry-1.docker.io/intel/chat-question-and-answer-core)
5. Image source and tags:
   • prebuilt registry tags, or
   • custom/private registry and tags
6. Model settings (EMBEDDING_MODEL, LLM_MODEL, optional RERANKER_MODEL)
7. Optional Hugging Face token (HUGGINGFACEHUB_API_TOKEN) for OpenVINO
8. Optional proxy values (http_proxy, https_proxy, no_proxy)

If runtime/device values are missing, default to openvino + cpu.

If prebuilt images are used and tags are not specified by the user, default to the tags in chart/values.yaml.

Use Helm and kubectl commands for deployment actions in this skill.

Decision Logic

• If runtime is ollama:
  • select -f values.yaml -f values-ollama.yaml
  • force CPU-only devices
• If runtime is openvino and device is gpu:
  • select -f values.yaml -f values-openvino.yaml
  • set gpu.enabled=true
  • require gpu.key from cluster labels
• If runtime is openvino and device is cpu:
  • select -f values.yaml -f values-openvino.yaml
  • set gpu.enabled=false
• If requested values conflict with chart validation (for example GPU model device with gpu.enabled=false), correct values before install.

Compose and setup_env.sh Translation

Use the reference mapping in ./references/compose-setupenv-to-helm-mapping.md if the user asks to map Compose or setup_env.sh inputs to Helm values.

Deployment Workflow

Run from sample-applications/chat-question-and-answer-core.

1. Preflight

kubectl version --client
helm version
kubectl config current-context

如果使用本地源 chart：

cd chart
helm dependency build

如果使用 OCI chart：

helm pull oci://registry-1.docker.io/intel/chat-question-and-answer-core --version <version>
tar -xvf chat-question-and-answer-core-<version>.tgz
cd chat-question-and-answer-core
helm dependency build

确保命名空间已存在：

kubectl create namespace <namespace> --dry-run=client -o yaml | kubectl apply -f -

2. 构建 values 覆盖文件

根据参考映射，将用户意图或 Compose/setup_env 风格的输入转换为 values-override.yaml，并创建或更新该文件。不要提交已填入的机密或令牌。

如果在代理后运行，请使用当前系统环境中的值，在 values-override.yaml 中包含以下键：

global:
	http_proxy: "${http_proxy}"
	https_proxy: "${https_proxy}"
	no_proxy: "${no_proxy}"

根据运行时选择基础文件：

• OpenVINO：values.yaml + values-openvino.yaml + values-override.yaml
• Ollama：values.yaml + values-ollama.yaml + values-override.yaml

3. 验证渲染后的清单

helm template chatqna-core \
	-f values.yaml \
	-f values-<runtime>.yaml \
	-f values-override.yaml \
	.

4. 安装或升级 release

helm upgrade --install chatqna-core \
	-f values.yaml \
	-f values-<runtime>.yaml \
	-f values-override.yaml \
	. \
	--namespace <namespace>

5. 验证部署

kubectl get pods -n <namespace>
kubectl get services -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp | tail -n 30
kubectl rollout status deploy/chatqna-core -n <namespace>
kubectl rollout status deploy/chatqna-core-nginx -n <namespace>

健康端点证据：

chatqna_hostip=$(kubectl get pods -l app=chatqna-core-nginx -n <namespace> -o jsonpath='{.items[0].status.hostIP}')
chatqna_port=$(kubectl get service chatqna-core-nginx -n <namespace> -o jsonpath='{.spec.ports[0].nodePort}')
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${chatqna_hostip}:${chatqna_port}/v1/chatqna/health"

6. 访问和拆除

# UI
echo "http://${chatqna_hostip}:${chatqna_port}"

# API docs
echo "http://${chatqna_hostip}:${chatqna_port}/v1/chatqna/docs"

# Uninstall
helm uninstall chatqna-core -n <namespace>

故障处理

• Helm 模板验证失败：
  • 报告导致失败的确切键，并建议修正后的键/值。
• 请求 GPU 但缺少 gpu.key：
  • 指示用户运行 kubectl describe node 并提供设备插件键， 然后使用 gpu.enabled=true 重新运行。
• Pod 未就绪：
  • 收集故障 Pod 的 kubectl describe pod 和 kubectl logs。
• 健康检查返回非 200：
  • 检查 chatqna-core 日志，排查模型下载/配置问题。
  • 提示首次启动可能会因拉取/转换模型而耗时更久。
• PVC 卡住：
  • 列出卡住的 PVC；仅在用户明确请求时才选择删除。
• 需要更多存储空间：
  • 增大 values-override.yaml 中的 PVC 容量，然后重新运行 helm upgrade。

完成标准

1. 使用正确的 values 文件执行特定运行时的安装命令。
2. 将 Compose/setup_env 输入（如有）转换为具体的 values-override.yaml。
3. 目标命名空间中的 Pod/服务运行正常。
4. 健康端点返回 HTTP_STATUS:200。
5. 向用户提供 UI URL、API 文档 URL、release/命名空间以及卸载命令。
6. 回复中包含原始验证证据（kubectl get、rollout 状态、 健康检查输出）。