chatqna-docker-deploy

ChatQnA Docker 部署

使用 Docker Compose 将 Chat Question and Answer Core 示例应用部署为容器。

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

此技能的产出

• 在以下某个后端配置上运行 ChatQnA Core 部署：
  • OpenVINO CPU（OPENVINO）
  • OpenVINO GPU（OPENVINO-GPU）
  • Ollama CPU（OLLAMA）
• 使用容器状态、日志和健康检查端点验证启动状态。
• 一份简洁的部署报告，包含：
  • 选定的运行时配置
  • 使用的镜像来源（预构建标签或本地构建）
  • 使用的是固定默认标签还是用户提供的标签
  • 访问 URL 和 API 文档 URL
  • 任何警告（令牌／模型／设备限制）

适用场景

• “部署 chat question and answer core”
• “启动 chatqna 容器”
• “运行 chatqna 的 docker compose”
• “部署 OpenVINO GPU 配置”
• “部署 ollama 后端”

需要确认的输入

运行命令前，确认或推断以下值：

1. 后端／运行时：openvino 或 ollama
2. 设备：cpu 或 gpu（GPU 仅适用于 OpenVINO）
3. 镜像来源：
   • 预构建的注册表镜像（REGISTRY、BACKEND_TAG、UI_TAG），或
   • 本地源代码构建（标签通常为 latest）
4. 可选的模型配置路径：MODEL_CONFIG_PATH
5. 可选的 Hugging Face 令牌，用于私有／受限模型：HUGGINGFACEHUB_API_TOKEN

如果未提供运行时／设备值，默认使用 openvino + cpu。

如果使用预构建镜像且用户未指定标签，则默认使用固定的发行版标签。

此技能中的部署操作仅使用 Docker Compose 命令。

决策逻辑

• 如果后端是 ollama：
  • 强制使用 CPU 路径
  • 使用 source scripts/setup_env.sh -b ollama
• 如果后端是 openvino 且设备是 gpu：
  • 使用 source scripts/setup_env.sh -d gpu
  • 如果 /dev/dri/render* 不存在，则发出警告并回退到 CPU 路径
• 其他情况：
  • 使用 source scripts/setup_env.sh（OpenVINO CPU）

部署工作流

从 sample-applications/chat-question-and-answer-core 目录运行。

1. 部署前检查

docker --version
docker compose version

如果用户要求使用预构建镜像但未提供标签，则使用固定的默认值：

export REGISTRY="intel/"
export BACKEND_TAG="core_1.3.3"      # or core_gpu_1.3.3 / core_ollama_1.3.3
export UI_TAG="core_1.3.3"

如果用户明确提供了不同的标签或注册表，则使用这些值，而不是固定默认值。

可选的模型配置覆盖：

export MODEL_CONFIG_PATH="/absolute/path/to/config.yaml"

可选的受限／私有模型令牌：

export HUGGINGFACEHUB_API_TOKEN="<token>"

2. 选择配置并导出环境

必须且只能选择一项：

# OpenVINO CPU (default)
source scripts/setup_env.sh

# OpenVINO GPU
source scripts/setup_env.sh -d gpu

# Ollama CPU
source scripts/setup_env.sh -b ollama

3. 启动容器

默认以分离模式启动：

docker compose -f docker/compose.yaml up -d

4. 验证部署

docker compose -f docker/compose.yaml ps
docker compose -f docker/compose.yaml logs --tail=150
curl -sf "http://${HOST_IP:-127.0.0.1}:8102/v1/chatqna/health"

处理部署请求时，请在回复中附上原始命令输出作为证据：

• docker compose -f docker/compose.yaml ps 的输出，显示预期服务状态为 Up。
• 以下命令的健康检查输出和 HTTP 状态： curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${HOST_IP:-127.0.0.1}:8102/v1/chatqna/health"

预期的就绪指示：

• 后端容器状态为 running
• UI 容器状态为 running
• 所选配置对应的 nginx 容器状态为 running
• 健康检查端点返回成功

访问 URL：

• UI：http://<HOST_IP>:8102
• API 文档：http://<HOST_IP>:8102/v1/chatqna/docs

5. 停止或重置

# Stop and remove service containers
docker compose -f docker/compose.yaml down

# Evidence: show running containers after shutdown
docker ps

# Optional deep cleanup (only when explicitly requested)
docker compose -f docker/compose.yaml down -v --remove-orphans

处理停止请求时，请在回复中附上完整的 docker ps 输出，作为容器已终止的证据。

完全停止状态的预期证据：

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

故障处理

• setup_env.sh 返回不受支持的后端／设备：
  • 修正为以下有效值之一：openvino 或 ollama；设备为 cpu／gpu
• 请求 GPU 但没有 render 节点：
  • 继续使用 OpenVINO CPU，并报告回退情况
• 容器启动失败：
  • 收集 docker compose ... logs --tail=200
  • 报告故障服务名称和第一个可采取措施的错误
• 启动后健康检查失败：
  • 检查后端日志，并确认 HOST_IP、配置和模型下载状态
  • 注意，首次启动可能因模型下载／转换而耗时更长

完成标准

1. 请求的运行配置文件已成功启动。
2. docker compose ps 显示预期服务正在运行。
3. 健康检查端点可通过 /v1/chatqna/health 访问。
4. 用户已获得访问 URL、API 文档 URL、准确的停止命令以及所用镜像标签。
5. 对于部署请求，响应包含原始 docker compose ps 输出和原始健康检查输出，其中包含 HTTP_STATUS:200，作为就绪证据。
6. 对于停止请求，响应包含原始 docker ps 输出，作为终止证据；完全停止的状态应符合以下格式： CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES