推理服务的客户端不应依赖模型进程内部细节。把请求 schema、超时、最大输入、健康检查和错误码定义成接口契约,替换运行时也不会影响调用方。
核心概念
区分 liveness、readiness 和业务推理接口。readiness 应在模型加载、Tokenizer 和依赖检查完成后才返回成功;请求要有 request_id 和输入长度上限。
可运行示例
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
app = FastAPI()
class GenerateRequest(BaseModel):
prompt: str = Field(min_length=1, max_length=8000)
max_tokens: int = Field(default=128, ge=1, le=2048)
@app.get('/ready')
def ready() -> dict:
return {'status': 'ready'}
@app.post('/generate')
def generate(request: GenerateRequest) -> dict:
if request.prompt.strip() == '':
raise HTTPException(status_code=422, detail='empty prompt')
return {'text': request.prompt[:32], 'request_id': 'local-example'}
操作步骤
- 先写 OpenAPI schema 和错误码,再绑定具体模型。
- 实现 /live、/ready 和推理接口,并为每个请求生成关联 id。
- 设置请求体、并发数、超时和输出长度上限。
- 使用固定输入验证成功、超时、过长输入和模型未就绪。
适用场景
适合内部服务、边缘部署和需要替换 vLLM、TGI 或自研运行时的团队。
常见问题
/live 可以加载模型吗? 不应,liveness 只说明进程还活着。
客户端超时后能无限重试吗? 不能,应限制重试并使用幂等请求 id。
官方参考
FastAPI 官方文档;Kubernetes probes。
最后核对日期:2026-11-16。版本、接口和安全边界以链接的官方资料为准;本文不虚构性能或费用结论。
