1. TGI环境搭建与基础验证

任务目标

在本机（Linux x86_64，已安装 NVIDIA 驱动与 Docker）上，通过 Docker 方式启动 Hugging Face TGI（Text Generation Inference）服务，加载 Qwen/Qwen2.5-0.5B-Instruct 模型，并调用其 HTTP API 验证文本生成功能正常。

环境依赖

• NVIDIA GPU（显存 ≥ 2GB，用于 0.5B 模型）
• NVIDIA Container Toolkit（nvidia-smi 可在容器内访问）
• Docker Engine ≥ 19.03
• curl（用于 API 验证）

启动 TGI 服务

拉取 TGI 镜像并启动容器。使用 --shm-size 避免共享内存不足，通过 --gpus all 暴露 GPU 给容器。

# 拉取镜像（约 2GB）
docker pull ghcr.io/huggingface/text-generation-inference:2.4.1

# 启动服务（模型首次启动会自动下载，约 1GB）
docker run --gpus all --shm-size 1g \
  -p 8080:80 \
  -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:2.4.1 \
  --model-id Qwen/Qwen2.5-0.5B-Instruct \
  --max-input-tokens 1024 \
  --max-total-tokens 2048

等待日志中出现 Connected 或 Ready 字样，表示服务已就绪（首次启动需下载模型，耗时取决于网络）。

验证 API 响应

服务启动后，在另一个终端执行以下请求，验证文本生成是否正常：

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "messages": [
      {"role": "user", "content": "什么是大语言模型？请用一句话回答。"}
    ],
    "max_tokens": 100,
    "temperature": 0.7
  }'

预期输出与判定标准

若服务正常，curl 将返回 JSON 格式响应，其中 choices[0].message.content 包含模型生成的文本（内容与模型推理结果一致，非固定值）。HTTP 状态码为 200，且响应中包含 id、created、usage 等字段。

通过条件：

• curl 请求返回 HTTP 200
• 响应 JSON 中 choices 数组非空，且 message.content 为有意义的自然语言文本
• 服务日志无 Error 或 Traceback 输出

常见问题排查

• 端口冲突：若 8080 被占用，修改 -p 映射为其他宿主机端口（如 -p 8081:80），验证时同步修改 URL。
• GPU 不可见：容器内执行 nvidia-smi 确认 GPU 可用；若失败，检查 NVIDIA Container Toolkit 安装。
• 模型下载慢：可设置环境变量 HF_ENDPOINT=https://hf-mirror.com 加速下载（在 docker run 前添加 -e HF_ENDPOINT=https://hf-mirror.com）。