大模型原理与训练 / 系统课时

构建推理接口

构建推理接口

本课把分词、模型推理和结果整理封装成一个可调用的 HTTP 服务。完成后,你将得到一个能校验参数、复用已加载模型、限制并发并返回生成耗时的最小推理接口。

学习目标

  • 设计清晰的推理请求与响应结构
  • 使用 FastAPI 封装完整的文本生成链路
  • 通过健康检查和接口调用验证服务可用性

明确接口边界与处理链路

一个可维护的推理接口不应让路由函数直接堆满模型细节。请求进入后,应依次完成参数校验、分词、张量迁移、模型生成、解码和响应组装;模型与分词器则在进程启动时加载一次,避免每个请求重复占用时间和显存。

推理接口的数据处理链路

请求参数只暴露业务真正需要控制的选项,例如提示词、最大生成长度、温度和 top_p。设备选择、张量搬运、模型对象和异常堆栈属于服务内部实现,不应由调用方传入或直接返回。

实现最小 FastAPI 服务

先安装运行依赖。示例使用 distilgpt2,便于在 CPU 或单张 GPU 上验证接口结构;替换模型时,接口契约可以保持不变。

bash
python -m pip install fastapi "uvicorn[standard]" torch transformers

预期输出

text
Successfully installed <PACKAGES>

将下面的完整代码保存为 app.py。代码在启动阶段加载模型,使用 torch.inference_mode() 关闭梯度记录,并通过异步锁避免多个请求同时争抢同一张设备。

python
import asyncio
import logging
import time
from contextlib import asynccontextmanager

import torch
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from transformers import AutoModelForCausalLM, AutoTokenizer

MODEL_NAME = "distilgpt2"
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"

logger = logging.getLogger("inference-api")
tokenizer = None
model = None
generate_lock = asyncio.Lock()

class GenerateRequest(BaseModel):
    prompt: str = Field(min_length=1, max_length=2000)
    max_new_tokens: int = Field(default=64, ge=1, le=128)
    temperature: float = Field(default=0.0, ge=0.0, le=2.0)
    top_p: float = Field(default=0.9, gt=0.0, le=1.0)

class GenerateResponse(BaseModel):
    text: str
    generated_tokens: int
    latency_ms: float

@asynccontextmanager
async def lifespan(app: FastAPI):
    global tokenizer, model

    # 模型只在进程启动时加载一次,避免请求内重复初始化。
    tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
    if tokenizer.pad_token_id is None:
        tokenizer.pad_token = tokenizer.eos_token

    model = AutoModelForCausalLM.from_pretrained(MODEL_NAME)
    model.to(DEVICE)
    model.eval()
    yield

app = FastAPI(title="Transformer Inference API", lifespan=lifespan)

def generate_text(request: GenerateRequest) -> GenerateResponse:
    if tokenizer is None or model is None:
        raise RuntimeError("model is not initialized")

    inputs = tokenizer(
        request.prompt,
        return_tensors="pt",
        truncation=True,
        max_length=512,
    ).to(DEVICE)

    generate_options = {
        "max_new_tokens": request.max_new_tokens,
        "do_sample": request.temperature > 0,
        "pad_token_id": tokenizer.pad_token_id,
    }
    if request.temperature > 0:
        generate_options["temperature"] = request.temperature
        generate_options["top_p"] = request.top_p

    started_at = time.perf_counter()
    with torch.inference_mode():
        output_ids = model.generate(**inputs, **generate_options)
    latency_ms = (time.perf_counter() - started_at) * 1000

    prompt_length = inputs["input_ids"].shape[1]
    generated_ids = output_ids[0, prompt_length:]
    text = tokenizer.decode(generated_ids, skip_special_tokens=True)

    return GenerateResponse(
        text=text,
        generated_tokens=int(generated_ids.shape[0]),
        latency_ms=round(latency_ms, 2),
    )

@app.get("/health")
async def health() -> dict[str, str]:
    return {"status": "UP", "model": MODEL_NAME, "device": DEVICE}

@app.post("/generate", response_model=GenerateResponse)
async def generate(request: GenerateRequest) -> GenerateResponse:
    try:
        # 推理属于阻塞任务,放入工作线程,避免阻塞事件循环。
        async with generate_lock:
            return await asyncio.to_thread(generate_text, request)
    except RuntimeError as exc:
        logger.exception("model inference failed")
        if torch.cuda.is_available():
            torch.cuda.empty_cache()
        raise HTTPException(status_code=500, detail="model inference failed") from exc

预期结果

text
app.py 可通过 Python 语法检查;服务启动后提供 GET /health 与 POST /generate 两个接口。

启动并调用接口

启动服务时,开发环境可以使用单进程。单卡部署不要盲目增加 worker,因为每个 worker 都会各自加载一份模型。

bash
python -m uvicorn app:app --host 0.0.0.0 --port 8000

预期输出

text
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000

另开终端发送生成请求。动态生成文本、token 数和耗时会因设备、模型缓存和输入内容不同而变化。

bash
curl -s http://127.0.0.1:8000/generate   -H "Content-Type: application/json"   -d '{"prompt":"Transformer models can","max_new_tokens":32,"temperature":0}'

预期输出

text
{"text":"<GENERATED_TEXT>","generated_tokens":<TOKEN_COUNT>,"latency_ms":<LATENCY_MS>}

处理输入、并发与异常边界

输入长度必须和生成预算一起控制。示例把提示词截断到 512 个 token,并把 max_new_tokens 限制为 128,从而避免单个请求无限占用计算资源;生产环境还应根据模型上下文窗口校验“输入 token 数加生成 token 数”是否越界。

异步接口并不等于模型可以无限并发。单张 GPU 上同时执行多个 generate() 往往会抬高显存峰值并恶化尾延迟,因此示例先用锁串行化推理。需要更高吞吐量时,应改用动态批处理或专用推理引擎,而不是简单移除锁。

服务端不应把底层异常原文直接返回客户端。显存不足、模型未初始化和输入越界应记录完整日志,再映射为稳定的 HTTP 状态码与错误结构;网关层还应补充请求超时、请求体大小限制和追踪 ID。

验收接口是否可上线

最小验收至少覆盖健康检查、正常生成、空提示词、超长参数和并发请求。健康检查只能证明进程存活;更严格的就绪检查还应确认模型已经加载,并可执行一次极短的探针推理。

上线前确认同一输入在 temperature=0 时结果可复现,接口返回的 token 数与实际生成一致,连续请求不会持续增加显存。随后再记录首词延迟、生成速度和吞吐量,作为容量规划依据。

本课总结

  • 推理接口应把参数校验、分词、生成、解码和响应组装分成清晰链路
  • 模型必须在启动阶段复用,并使用推理模式、输入上限和并发控制保护资源
  • 健康检查与真实生成请求要分别验证,不能只凭端口可访问判断服务可用

下一课预告

下一课将建立可重复的性能压测方法,分别测量首词延迟、解码速度、批量吞吐量和峰值显存,并学习如何根据指标定位瓶颈。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构建推理接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通