ChatQnA 部署指南

本文档提供在 TKE 上部署 OPEA ChatQnA 的完整指南，包括手动部署和自动化部署两种方式。

📋 Document Metadata

API Version: 2024-03-03
Agent Friendliness: ⭐⭐⭐⭐⭐
Applicable Clusters: 标准 TKE / TKE+GPU / TKE 超级节点
Estimated Time: 30-45 分钟

🎯 功能概述

ChatQnA 是基于 OPEA 的检索增强生成（RAG）问答系统，特点：

✅ 基于私有知识库的智能问答
✅ 支持文档上传和向量化
✅ 高精度语义检索
✅ 大语言模型生成回答
✅ 可扩展的微服务架构

前置条件

集群要求

TKE 集群 Kubernetes 1.24+
至少 3 个工作节点
每节点至少 4 核 8GB 内存
集群总资源：20+ 核，40+ GB 内存
LoadBalancer 服务支持（TKE 默认支持）

工具要求

kubectl 已安装并配置
（可选）Python 3.8+ 用于自动化脚本
（可选）腾讯云 API 凭证用于创建集群

权限要求

集群管理员权限（创建 Namespace、Deployment、Service）
（如使用自动化）腾讯云 TKE API 权限

部署方式

方式 1: 自动化部署（推荐）

使用 Python Cookbook 脚本一键部署。

1.1 安装依赖

# 克隆项目
git clone https://github.com/your-org/ai-on-tke.git
cd ai-on-tke

# 安装依赖
pip install -r requirements.txt

1.2 配置凭证

# 复制配置模板
cp config/config.example.yaml config/config.yaml

# 编辑配置文件
vim config/config.yaml

配置示例：

tencent_cloud:
  secret_id: "YOUR_SECRET_ID"
  secret_key: "YOUR_SECRET_KEY"
  region: "ap-guangzhou"

tke:
  cluster_version: "1.28.3"
  vpc_cidr: "10.0.0.0/16"
  instance_type: "S5.LARGE8"  # 4核8GB

1.3 端到端部署

# 部署（包含创建集群）
python cookbook/scenarios/chatqna_e2e.py \
  --cluster-name opea-demo \
  --region ap-guangzhou \
  --node-count 3 \
  --wait

# 输出示例:
# ✅ 创建 VPC: vpc-xxx
# ✅ 创建子网: subnet-xxx
# ✅ 创建集群: cls-xxx
# ✅ 创建节点池（3 节点）
# ✅ 等待集群就绪...
# ✅ 部署 ChatQnA 组件
# ✅ 验证部署成功
#
# Gateway 访问地址: http://123.45.67.89:8888

1.4 部署到现有集群

如果已有 TKE 集群：

python cookbook/opea/deploy_chatqna.py \
  --cluster-id cls-xxx \
  --namespace opea-system \
  --wait

方式 2: 手动 kubectl 部署

使用 Kubernetes YAML 文件手动部署。

2.1 创建命名空间

kubectl apply -f- <<EOF
apiVersion: v1
kind: Namespace
metadata:
  name: opea-system
  labels:
    name: opea-system
spec:
  resourceQuota:
    hard:
      requests.cpu: "50"
      requests.memory: "100Gi"
EOF

2.2 创建 ConfigMap

kubectl apply -f manifests/chatqna/configmap.yaml

2.3 部署组件（按顺序）

# 1. Redis 向量数据库
kubectl apply -f manifests/chatqna/redis.yaml

# 2. Embedding 服务
kubectl apply -f manifests/chatqna/embedding.yaml

# 3. Retrieval 服务
kubectl apply -f manifests/chatqna/retrieval.yaml

# 4. Reranking 服务
kubectl apply -f manifests/chatqna/rerank.yaml

# 5. LLM 服务（需要较长时间）
kubectl apply -f manifests/chatqna/llm.yaml

# 6. DataPrep 服务
kubectl apply -f manifests/chatqna/dataprep.yaml

# 7. Gateway 服务
kubectl apply -f manifests/chatqna/gateway.yaml

2.4 等待部署完成

# 查看 Pod 状态
kubectl get pods -n opea-system -w

# 等待所有 Pod 就绪
kubectl wait --for=condition=ready pod \
  -l app=chatqna \
  -n opea-system \
  --timeout=900s

验证部署

检查服务状态

# 检查所有 Pod
kubectl get pods -n opea-system

# 期望输出（所有 Pod Running）:
# NAME                                READY   STATUS    AGE
# chatqna-redis-xxx                   1/1     Running   5m
# chatqna-embedding-xxx               2/2     Running   5m
# chatqna-retrieval-xxx               1/1     Running   5m
# chatqna-rerank-xxx                  2/2     Running   5m
# chatqna-llm-xxx                     2/2     Running   8m
# chatqna-dataprep-xxx                1/1     Running   5m
# chatqna-gateway-xxx                 1/1     Running   5m

检查服务端点

# 获取 Gateway 服务
kubectl get svc chatqna-gateway -n opea-system

# 输出:
# NAME               TYPE           EXTERNAL-IP     PORT(S)
# chatqna-gateway    LoadBalancer   123.45.67.89    8888:30123/TCP

API 健康检查

export GATEWAY_IP=<EXTERNAL-IP>

# 健康检查
curl http://${GATEWAY_IP}:8888/v1/health

# 期望返回:
# {"status": "healthy"}

功能测试

# 测试问答
curl -X POST http://${GATEWAY_IP}:8888/v1/chatqna \
  -H "Content-Type: application/json" \
  -d '{
    "messages": "What is TKE?",
    "max_tokens": 100
  }'

# 期望返回 JSON 格式的答案

数据导入

上传文本文件

# 准备测试文档
echo "TKE is Tencent Kubernetes Engine..." > test-doc.txt

# 上传文档
curl -X POST http://${GATEWAY_IP}:6007/v1/dataprep \
  -F "files=@test-doc.txt"

# 返回:
# {"status": "success", "file_id": "xxx"}

批量导入 URL

curl -X POST http://${GATEWAY_IP}:6007/v1/dataprep \
  -H "Content-Type: application/json" \
  -d '{
    "link_list": [
      "https://cloud.tencent.com/document/product/457",
      "https://kubernetes.io/docs/"
    ]
  }'

验证数据导入

# 查询导入的文档
curl http://${GATEWAY_IP}:6007/v1/dataprep/list

# 使用导入的数据测试
curl -X POST http://${GATEWAY_IP}:8888/v1/chatqna \
  -H "Content-Type: application/json" \
  -d '{
    "messages": "Tell me about TKE features",
    "max_tokens": 200
  }'

故障排查

Pod 启动失败

# 查看 Pod 详情
kubectl describe pod <pod-name> -n opea-system

# 常见问题：
# 1. ImagePullBackOff - 镜像拉取失败
#    解决：检查网络，使用镜像加速
# 2. Insufficient resources - 资源不足
#    解决：添加节点或减少资源请求
# 3. CrashLoopBackOff - 容器崩溃
#    解决：查看日志排查问题

服务无法访问

# 检查服务端点
kubectl get endpoints -n opea-system

# 检查网络策略
kubectl get networkpolicies -n opea-system

# 测试 Pod 间连接
kubectl exec -it chatqna-gateway-xxx -n opea-system -- \
  curl http://chatqna-embedding:6000/v1/health

LLM 响应慢

原因: CPU 推理性能有限

优化方案:

使用 GPU 节点（推荐）

# 修改 llm.yaml
spec:
  template:
    spec:
      nodeSelector:
        accelerator: nvidia-tesla-t4
      containers:
      - name: vllm-service
        resources:
          limits:
            nvidia.com/gpu: 1

增加副本数

kubectl scale deployment chatqna-llm -n opea-system --replicas=2

使用更小的模型

修改 ConfigMap 中的 LLM_MODEL_ID。

监控和日志

查看日志

# Gateway 日志
kubectl logs -f deployment/chatqna-gateway -n opea-system

# LLM 服务日志（双容器）
kubectl logs -f deployment/chatqna-llm -n opea-system -c llm
kubectl logs -f deployment/chatqna-llm -n opea-system -c vllm-service

# 所有组件日志
kubectl logs -l app=chatqna -n opea-system --tail=100

资源监控

# Pod 资源使用
kubectl top pods -n opea-system

# 节点资源使用
kubectl top nodes

部署 Prometheus 监控（可选）

参考 TKE 监控最佳实践配置 Prometheus 和 Grafana。

清理资源

删除 ChatQnA 部署

# 删除所有组件
kubectl delete namespace opea-system

# 或使用脚本
python cookbook/opea/cleanup.py --cluster-id cls-xxx

删除 TKE 集群

# 使用脚本删除
python cookbook/cluster/delete_cluster.py \
  --cluster-id cls-xxx \
  --region ap-guangzhou

# 或通过 TKE 控制台删除

Agent Prompt 模板

以下是供 AI Agent 使用的提示词模板：

请在 TKE 上部署 OPEA ChatQnA 应用。

要求:
1. 使用自动化脚本部署
2. 集群名称: opea-demo
3. 区域: ap-guangzhou
4. 节点数: 3
5. 等待部署完成并验证

执行命令:
python cookbook/scenarios/chatqna_e2e.py \
  --cluster-name opea-demo \
  --region ap-guangzhou \
  --node-count 3 \
  --wait

验证步骤:
1. 检查所有 Pod 状态
2. 测试 API 健康检查
3. 上传测试文档
4. 测试问答功能

预期结果:
所有组件正常运行，API 返回正确答案。

ChatQnA 部署指南

ChatQnA 部署指南

📋 Document Metadata

🎯 功能概述

前置条件

集群要求

工具要求

权限要求

部署方式

方式 1: 自动化部署（推荐）

1.1 安装依赖

1.2 配置凭证

1.3 端到端部署

1.4 部署到现有集群

方式 2: 手动 kubectl 部署

2.1 创建命名空间

2.2 创建 ConfigMap

2.3 部署组件（按顺序）

2.4 等待部署完成

验证部署

检查服务状态

检查服务端点

API 健康检查

功能测试

数据导入

上传文本文件

批量导入 URL

验证数据导入

故障排查

Pod 启动失败

服务无法访问

LLM 响应慢

监控和日志

查看日志

资源监控

部署 Prometheus 监控（可选）

清理资源

删除 ChatQnA 部署

删除 TKE 集群

Agent Prompt 模板

相关资源