TGI — HuggingFace 文本生成推理¶

# === Docker 部署（推荐，最简单） ===

# 运行 Llama 3.1 8B 模型
docker run --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  -v /data/models:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.0 \
  --model-id meta-llama/Llama-3.1-8B-Instruct  # 指定要部署的模型

# 参数解释：
# --gpus all        — 使用所有 GPU
# --shm-size 1g     — 共享内存（必须设，否则高并发会报错）
# -p 8080:80        — 端口映射（访问 localhost:8080）
# -v /data/models   — 模型缓存目录
# --model-id        — HuggingFace 上的模型 ID

# 等待模型下载和加载（首次较慢）
# 看到 "Ready" 字样表示启动成功

# 部分模型需要 HuggingFace Token（如 Llama 系列）
# 先在 https://huggingface.co/settings/tokens 获取 Token

docker run --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  -e HUGGING_FACE_HUB_TOKEN=hf_你的token \
  ghcr.io/huggingface/text-generation-inference:3.3.0 \
  --model-id meta-llama/Llama-3.1-8B-Instruct  # 带 Token 运行

# 健康检查
curl http://localhost:8080/health  # 检查服务是否正常

# 生成文本
curl http://localhost:8080/generate \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": "什么是宏基因组学？请用简单的语言解释。",
    "parameters": {
      "max_new_tokens": 500,
      "temperature": 0.7,
      "top_p": 0.9
    }
  }'
# 返回生成的文本

from openai import OpenAI  # 导入 OpenAI SDK

# 用 OpenAI SDK 连接 TGI
client = OpenAI(
    base_url="http://localhost:8080/v1",  # TGI 的 OpenAI 兼容端点
    api_key="tgi"  # TGI 不需要真实 Key
)

# 对话
response = client.chat.completions.create(
    model="tgi",  # 模型名（TGI 只加载一个模型，所以随便填）
    messages=[
        {"role": "system", "content": "你是一个生物信息学助手。"},
        {"role": "user", "content": "FASTQ 和 FASTA 格式有什么区别？"}
    ],
    max_tokens=500,  # 最大输出 token 数
    stream=True  # 流式输出
)

for chunk in response:  # 逐块接收
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")  # 实时打印

import requests  # 导入 HTTP 请求库

# TGI 原生 API 调用
response = requests.post(
    "http://localhost:8080/generate",  # TGI 生成端点
    json={
        "inputs": "解释16S rRNA基因在微生物分类中的作用",  # 输入文本
        "parameters": {
            "max_new_tokens": 500,  # 最大新 token 数
            "temperature": 0.7,  # 温度参数
            "repetition_penalty": 1.1  # 重复惩罚
        }
    }
)

result = response.json()  # 解析 JSON
print(result[0]["generated_text"])  # 打印生成的文本

# TGI v3 引入了零配置模式
# 如果不手动设置参数，TGI 会自动检测硬件并优化

docker run --gpus all \
  --shm-size 1g \
  -p 8080:80 \
  ghcr.io/huggingface/text-generation-inference:3.3.0 \
  --model-id meta-llama/Llama-3.1-8B-Instruct
  # 不需要手动设置 max-input-length、max-batch-size 等
  # TGI 自动检测 GPU 显存并设置最优值

# FP8 量化（推荐，精度损失最小）
docker run --gpus all --shm-size 1g -p 8080:80 \
  ghcr.io/huggingface/text-generation-inference:3.3.0 \
  --model-id meta-llama/Llama-3.1-70B-Instruct \
  --quantize fp8  # FP8 量化，显存减半

# AWQ 4-bit 量化
docker run --gpus all --shm-size 1g -p 8080:80 \
  ghcr.io/huggingface/text-generation-inference:3.3.0 \
  --model-id TheBloke/Llama-3.1-7B-AWQ \
  --quantize awq  # AWQ 量化

# BitsAndBytes 量化（任何 GPU 都能用）
docker run --gpus all --shm-size 1g -p 8080:80 \
  ghcr.io/huggingface/text-generation-inference:3.3.0 \
  --model-id meta-llama/Llama-3.1-8B-Instruct \
  --quantize bitsandbytes  # BNB INT8 量化

# 使用多张 GPU 运行大模型
docker run --gpus all --shm-size 1g -p 8080:80 \
  ghcr.io/huggingface/text-generation-inference:3.3.0 \
  --model-id meta-llama/Llama-3.1-70B-Instruct \
  --num-shard 4  # 分到 4 张 GPU 上

# num-shard = GPU 数量
# TGI 自动做张量并行

# TGI v3 支持使用其他推理引擎作为后端

# 使用 vLLM 作为后端
docker run --gpus all --shm-size 1g -p 8080:80 \
  ghcr.io/huggingface/text-generation-inference:3.3.0 \
  --model-id meta-llama/Llama-3.1-8B-Instruct \
  --backend vllm  # 使用 vLLM 后端

# 使用 TensorRT-LLM 作为后端（NVIDIA 优化）
docker run --gpus all --shm-size 1g -p 8080:80 \
  ghcr.io/huggingface/text-generation-inference:3.3.0 \
  --model-id meta-llama/Llama-3.1-8B-Instruct \
  --backend trt-llm  # 使用 TensorRT-LLM 后端

# k8s-tgi-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tgi-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tgi
  template:
    metadata:
      labels:
        app: tgi
    spec:
      containers:
      - name: tgi
        image: ghcr.io/huggingface/text-generation-inference:3.3.0
        args:
          - "--model-id"
          - "meta-llama/Llama-3.1-8B-Instruct"  # 模型ID
        ports:
          - containerPort: 80
        resources:
          limits:
            nvidia.com/gpu: 1  # 请求1个GPU
        volumeMounts:
          - name: model-cache
            mountPath: /data
        env:
          - name: HUGGING_FACE_HUB_TOKEN
            valueFrom:
              secretKeyRef:
                name: hf-secret
                key: token
      volumes:
        - name: model-cache
          persistentVolumeClaim:
            claimName: tgi-model-pvc