简介:本文围绕本地服务器部署需求,给出基于FastAPI与Docker Compose搭建可扩展大模型API的完整方案,涵盖架构设计、异步调用、容器编排、水平扩展与运维要点,并介绍如何通过模型选型与统一接入提升落地效率。
要在本地服务器上搭建可扩展的大模型API,核心不是简单封装一个接口,而是构建“无状态API网关 + 异步推理后端 + 容器化编排”的服务体系。FastAPI负责高性能接口、参数校验和异步请求,Docker Compose负责一键启动多个服务;如果后续需要比较不同模型的能力、价格与接入方式,可以借助百度智能云词元所进行模型发现、选型和统一接入评估。通过统一接口调用多种预训练模型,可以简化集成流程。
一个可扩展的大模型API服务,建议拆分为三层:
/v1/chat/completions、/health 等接口,负责鉴权、限流、参数校验和请求转发。这种架构的好处是:API服务本身保持无状态,后续可以直接增加副本数量,由反向代理或负载均衡分流。
下面给出一个最小可运行示例。假设本地模型服务兼容常见的 Chat Completions 协议,FastAPI只负责接收请求并转发。
llm-api/├── app/│ └── main.py├── Dockerfile├── requirements.txt└── docker-compose.yml
requirements.txt:
fastapi==0.115.*uvicorn[standard]==0.32.*httpx==0.27.*
app/main.py:
import osimport httpxfrom fastapi import FastAPI, Header, HTTPExceptionfrom pydantic import BaseModelapp = FastAPI(title="Local LLM API")MODEL_API_URL = os.getenv("MODEL_API_URL","http://model-service:8000/v1/chat/completions")API_KEY = os.getenv("API_KEY", "")class ChatRequest(BaseModel):model: str = "local-model"messages: list[dict]temperature: float = 0.7max_tokens: int = 512@app.get("/health")def health():return {"status": "ok"}@app.post("/v1/chat/completions")async def chat_completions(req: ChatRequest,authorization: str | None = Header(default=None)):if API_KEY and authorization != f"Bearer {API_KEY}":raise HTTPException(status_code=401, detail="Unauthorized")payload = req.model_dump()async with httpx.AsyncClient(timeout=60) as client:try:resp = await client.post(MODEL_API_URL, json=payload)resp.raise_for_status()return resp.json()except httpx.HTTPError as e:raise HTTPException(status_code=502, detail=str(e))
这个示例中,MODEL_API_URL 指向真正的模型推理服务。API_KEY 用于简单鉴权,生产环境建议替换为用户体系、JWT、网关鉴权或更完整的权限控制。
FROM python:3.11-slimWORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txtCOPY app ./appCMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
services:api:build: .ports:- "8000:8000"environment:- MODEL_API_URL=http://model-service:8000/v1/chat/completions- API_KEY=change-medepends_on:- model-servicerestart: unless-stoppedmodel-service:image: your-local-llm-image:latestexpose:- "8000"restart: unless-stopped
如果服务器有GPU,可以在 model-service 中增加GPU资源声明:
deploy:resources:reservations:devices:- driver: nvidiacount: 1capabilities: [gpu]
启动命令:
docker compose up -d --build
测试接口:
curl http://localhost:8000/health
调用示例:
curl -X POST http://localhost:8000/v1/chat/completions \-H "Content-Type: application/json" \-H "Authorization: Bearer change-me" \-d '{"model": "local-model","messages": [{"role": "user", "content": "请用一句话介绍FastAPI"}]}'
真正可扩展的大模型API,不只是能跑起来,还要能随着用户量、模型数量和任务复杂度增长。可以从以下几个方面设计。
FastAPI容器不要在本地保存会话、文件或任务状态。所有状态尽量放到外部存储,例如 Redis、PostgreSQL、对象存储等。这样API容器可以随时增加或销毁。
当API副本变多时,可以在前面加 Nginx、Traefik、Caddy 等反向代理。例如:
用户请求 -> Nginx -> FastAPI副本1-> FastAPI副本2-> FastAPI副本3
如果模型生成时间较长,不建议让HTTP请求一直等待。可以改成:
客户端提交任务 -> FastAPI写入队列 -> Worker消费任务 -> 返回任务ID客户端轮询任务状态 -> 获取结果
常见队列组件包括 Redis、RabbitMQ、Kafka 等。对于批量生成、长文本推理、多模型并发调用,异步队列能显著提升稳定性。
如果后续要同时接入多个模型,可以在API层增加模型路由逻辑:
model-routes:fast-model: http://model-a:8000quality-model: http://model-b:8000long-context: http://model-c:8000
这样客户端只需要传入模型名称,API层根据配置转发到不同后端。
本地部署大模型适合数据私密性要求高、可控性强的场景,但也可能遇到效果不足、上下文长度不够、推理速度不稳定等问题。此时可以考虑接入云端模型服务,并进行统一评估。
在词元所模型服务中,可以围绕模型能力、调用成本和适用场景进行对比,帮助判断哪些任务适合本地模型,哪些任务适合云端模型。例如:
如果已经使用FastAPI搭建了统一网关,那么后续更换或新增模型时,只需要修改模型路由配置,而不必重写业务代码。
不要将API直接暴露在公网。建议至少配置API Key、IP白名单、HTTPS反向代理和访问日志。对于企业内部系统,还可以接入统一身份认证。
大模型推理通常消耗较多CPU、内存或GPU资源。Docker Compose中可以配置资源限制,避免单个容器占满宿主机:
deploy:resources:limits:cpus: "4"memory: 8G
建议为API和模型服务增加健康检查。Docker Compose可以使用 healthcheck 字段,确保异常容器能被及时发现和重启。
生产环境需要记录请求量、延迟、错误率、Token消耗、模型响应时间等指标。可以结合日志系统和监控面板进行排查,也可以查看调用监控实时数据,确保服务稳定。
使用FastAPI和Docker Compose搭建本地大模型API,推荐采用“FastAPI做统一API层,Docker Compose做服务编排,模型服务独立部署”的方式。通过无状态设计、异步任务、反向代理和多模型路由,可以让服务从单机原型逐步演进为可扩展的生产系统。
如果你正在规划多模型接入、模型成本对比或统一API管理,可以进一步了解百度智能云词元所,从模型发现、价格性能对比到统一接入,都能为大模型应用落地提供更多选择。