2. TGI 单机部署与文本生成测试

任务目标

在本案例中，你将使用 Hugging Face 的 Text Generation Inference (TGI) 在单机环境部署一个开源大语言模型，并通过其 HTTP API 完成一次文本生成请求，验证服务可用性。本案例以 Qwen/Qwen2.5-1.5B-Instruct 为例，该模型约 3GB，适合单卡或纯 CPU 环境验证。

环境与依赖

• 操作系统：Ubuntu 20.04+ / CentOS 8+（需支持 Docker）
• 硬件：建议 NVIDIA GPU（显存 ≥ 4GB），无 GPU 时可用 CPU 模式（速度较慢）
• 软件：Docker Engine 20.10+，NVIDIA Container Toolkit（仅 GPU 需要）
• 网络：可访问 Docker Hub 与 Hugging Face Hub

部署步骤

使用官方镜像 ghcr.io/huggingface/text-generation-inference:2.4.1。以下命令将模型挂载至容器内 /data 目录，并暴露 8080 端口。若使用 CPU，移除 --gpus all 并添加 --cpus 8 限制资源。

# GPU 部署
docker run -d --name tgi-server \
  --gpus all \
  -p 8080:80 \
  -v /root/.cache/huggingface:/data \
  ghcr.io/huggingface/text-generation-inference:2.4.1 \
  --model-id Qwen/Qwen2.5-1.5B-Instruct \
  --max-input-tokens 1024 \
  --max-total-tokens 2048

# CPU 部署（无 GPU 时）
docker run -d --name tgi-server \
  -p 8080:80 \
  -v /root/.cache/huggingface:/data \
  ghcr.io/huggingface/text-generation-inference:2.4.1 \
  --model-id Qwen/Qwen2.5-1.5B-Instruct \
  --max-input-tokens 512 \
  --max-total-tokens 1024 \
  --cpus 8

首次启动需下载模型，观察日志确认就绪：

docker logs -f tgi-server
# 看到 "Ready" 或 "Starting server" 后等待约 10 秒即可测试

文本生成测试

服务启动后，通过 /v1/chat/completions 端点发送对话请求。使用 curl 验证：

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-1.5B-Instruct",
    "messages": [
      {"role": "user", "content": "请用一句话介绍你自己。"}
    ],
    "max_tokens": 128,
    "temperature": 0.7
  }'

验证方法与通过条件

执行上述 curl 命令后，满足以下条件即判定部署成功：

• HTTP 状态码为 200 OK
• 响应 JSON 中包含 choices[0].message.content 字段，且内容为非空字符串
• 响应中的 model 字段值为 Qwen/Qwen2.5-1.5B-Instruct

预期输出（内容因采样随机性可能不同，但结构一致）：

{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "model": "Qwen/Qwen2.5-1.5B-Instruct",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我是通义千问，一个由阿里云开发的人工智能助手..."
      },
      "finish_reason": "stop"
    }
  ]
}

常见问题排查

• 端口冲突：若 8080 被占用，修改 -p 映射为其他端口（如 8081:80），测试时同步修改 URL。
• 模型下载失败：确认服务器可访问 huggingface.co，或提前执行 huggingface-cli download Qwen/Qwen2.5-1.5B-Instruct 手动下载至挂载目录。
• GPU 不可用：日志报 CUDA 错误时，改用 CPU 部署命令，并适当降低 --max-total-tokens 避免内存溢出。
• 服务未就绪：模型加载需 1-3 分钟，执行 docker logs tgi-server 确认无报错后重试。

停止与清理

docker stop tgi-server && docker rm tgi-server