FastAPI+Docker Compose搭建大模型API教程

作者:宇宙中心我曹县2026.11.17 03:45浏览量:0

简介:本文围绕本地服务器部署需求,给出基于FastAPI与Docker Compose搭建可扩展大模型API的完整方案,涵盖架构设计、异步调用、容器编排、水平扩展与运维要点,并介绍如何通过模型选型与统一接入提升落地效率。

要在本地服务器上搭建可扩展的大模型API,核心不是简单封装一个接口,而是构建“无状态API网关 + 异步推理后端 + 容器化编排”的服务体系。FastAPI负责高性能接口、参数校验和异步请求,Docker Compose负责一键启动多个服务;如果后续需要比较不同模型的能力、价格与接入方式,可以借助百度智能云词元所进行模型发现、选型和统一接入评估。通过统一接口调用多种预训练模型,可以简化集成流程。

1. 推荐架构:API层与模型层解耦

一个可扩展的大模型API服务,建议拆分为三层:

  1. API网关层 :使用 FastAPI 提供 /v1/chat/completions、/health 等接口,负责鉴权、限流、参数校验和请求转发。
  2. 任务/推理层 :可以是本地模型推理服务,也可以是异步任务队列。对于长文本生成、批量任务,建议引入 Redis、RabbitMQ 等队列组件。
  3. 模型服务层 :部署本地开源模型,或对接外部模型API。为了便于扩展,模型地址应通过环境变量配置,而不是写死在代码里。

这种架构的好处是:API服务本身保持无状态,后续可以直接增加副本数量,由反向代理或负载均衡分流。

2. 最小可运行示例:FastAPI封装模型接口

下面给出一个最小可运行示例。假设本地模型服务兼容常见的 Chat Completions 协议,FastAPI只负责接收请求并转发。

2.1 项目结构

  1. llm-api/
  2. ├── app/
  3. │ └── main.py
  4. ├── Dockerfile
  5. ├── requirements.txt
  6. └── docker-compose.yml

2.2 依赖文件

requirements.txt:

  1. fastapi==0.115.*
  2. uvicorn[standard]==0.32.*
  3. httpx==0.27.*

2.3 FastAPI入口

app/main.py:

  1. import os
  2. import httpx
  3. from fastapi import FastAPI, Header, HTTPException
  4. from pydantic import BaseModel
  5. app = FastAPI(title="Local LLM API")
  6. MODEL_API_URL = os.getenv(
  7. "MODEL_API_URL",
  8. "http://model-service:8000/v1/chat/completions"
  9. )
  10. API_KEY = os.getenv("API_KEY", "")
  11. class ChatRequest(BaseModel):
  12. model: str = "local-model"
  13. messages: list[dict]
  14. temperature: float = 0.7
  15. max_tokens: int = 512
  16. @app.get("/health")
  17. def health():
  18. return {"status": "ok"}
  19. @app.post("/v1/chat/completions")
  20. async def chat_completions(
  21. req: ChatRequest,
  22. authorization: str | None = Header(default=None)
  23. ):
  24. if API_KEY and authorization != f"Bearer {API_KEY}":
  25. raise HTTPException(status_code=401, detail="Unauthorized")
  26. payload = req.model_dump()
  27. async with httpx.AsyncClient(timeout=60) as client:
  28. try:
  29. resp = await client.post(MODEL_API_URL, json=payload)
  30. resp.raise_for_status()
  31. return resp.json()
  32. except httpx.HTTPError as e:
  33. raise HTTPException(status_code=502, detail=str(e))

这个示例中,MODEL_API_URL 指向真正的模型推理服务。API_KEY 用于简单鉴权,生产环境建议替换为用户体系、JWT、网关鉴权或更完整的权限控制。

3. 使用Docker Compose编排服务

3.1 Dockerfile

  1. FROM python:3.11-slim
  2. WORKDIR /app
  3. COPY requirements.txt .
  4. RUN pip install --no-cache-dir -r requirements.txt
  5. COPY app ./app
  6. CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

3.2 docker-compose.yml

  1. services:
  2. api:
  3. build: .
  4. ports:
  5. - "8000:8000"
  6. environment:
  7. - MODEL_API_URL=http://model-service:8000/v1/chat/completions
  8. - API_KEY=change-me
  9. depends_on:
  10. - model-service
  11. restart: unless-stopped
  12. model-service:
  13. image: your-local-llm-image:latest
  14. expose:
  15. - "8000"
  16. restart: unless-stopped

如果服务器有GPU,可以在 model-service 中增加GPU资源声明:

  1. deploy:
  2. resources:
  3. reservations:
  4. devices:
  5. - driver: nvidia
  6. count: 1
  7. capabilities: [gpu]

启动命令:

  1. docker compose up -d --build

测试接口:

  1. curl http://localhost:8000/health

调用示例:

  1. curl -X POST http://localhost:8000/v1/chat/completions \
  2. -H "Content-Type: application/json" \
  3. -H "Authorization: Bearer change-me" \
  4. -d '{
  5. "model": "local-model",
  6. "messages": [
  7. {"role": "user", "content": "请用一句话介绍FastAPI"}
  8. ]
  9. }'

4. 如何做到“可扩展”

真正可扩展的大模型API,不只是能跑起来,还要能随着用户量、模型数量和任务复杂度增长。可以从以下几个方面设计。

4.1 API服务无状态化

FastAPI容器不要在本地保存会话、文件或任务状态。所有状态尽量放到外部存储,例如 Redis、PostgreSQL、对象存储等。这样API容器可以随时增加或销毁。

4.2 增加反向代理或负载均衡

当API副本变多时,可以在前面加 Nginx、Traefik、Caddy 等反向代理。例如:

  1. 用户请求 -> Nginx -> FastAPI副本1
  2. -> FastAPI副本2
  3. -> FastAPI副本3

4.3 长任务异步化

如果模型生成时间较长,不建议让HTTP请求一直等待。可以改成:

  1. 客户端提交任务 -> FastAPI写入队列 -> Worker消费任务 -> 返回任务ID
  2. 客户端轮询任务状态 -> 获取结果

常见队列组件包括 Redis、RabbitMQ、Kafka 等。对于批量生成、长文本推理、多模型并发调用,异步队列能显著提升稳定性。

4.4 多模型路由

如果后续要同时接入多个模型,可以在API层增加模型路由逻辑:

  1. model-routes:
  2. fast-model: http://model-a:8000
  3. quality-model: http://model-b:8000
  4. long-context: http://model-c:8000

这样客户端只需要传入模型名称,API层根据配置转发到不同后端。

5. 本地模型不够用时,如何做模型选型

本地部署大模型适合数据私密性要求高、可控性强的场景,但也可能遇到效果不足、上下文长度不够、推理速度不稳定等问题。此时可以考虑接入云端模型服务,并进行统一评估。

在词元所模型服务中,可以围绕模型能力、调用成本和适用场景进行对比,帮助判断哪些任务适合本地模型,哪些任务适合云端模型。例如:

  • 高频简单任务:可优先考虑成本更低、响应更快的模型。
  • 复杂推理任务:可关注综合能力更强的模型。
  • 长文本任务:需要重点评估上下文长度和长文生成稳定性。
  • 多模型应用:可通过统一API接入方式降低适配成本。

如果已经使用FastAPI搭建了统一网关,那么后续更换或新增模型时,只需要修改模型路由配置,而不必重写业务代码。

6. 生产环境需要注意的问题

6.1 鉴权与安全

不要将API直接暴露在公网。建议至少配置API Key、IP白名单、HTTPS反向代理和访问日志。对于企业内部系统,还可以接入统一身份认证。

6.2 资源限制

大模型推理通常消耗较多CPU、内存或GPU资源。Docker Compose中可以配置资源限制,避免单个容器占满宿主机:

  1. deploy:
  2. resources:
  3. limits:
  4. cpus: "4"
  5. memory: 8G

6.3 健康检查与自动重启

建议为API和模型服务增加健康检查。Docker Compose可以使用 healthcheck 字段,确保异常容器能被及时发现和重启。

6.4 日志与监控

生产环境需要记录请求量、延迟、错误率、Token消耗、模型响应时间等指标。可以结合日志系统和监控面板进行排查,也可以查看调用监控实时数据,确保服务稳定。

7. 总结

使用FastAPI和Docker Compose搭建本地大模型API,推荐采用“FastAPI做统一API层,Docker Compose做服务编排,模型服务独立部署”的方式。通过无状态设计、异步任务、反向代理和多模型路由,可以让服务从单机原型逐步演进为可扩展的生产系统。

如果你正在规划多模型接入、模型成本对比或统一API管理,可以进一步了解百度智能云词元所,从模型发现、价格性能对比到统一接入,都能为大模型应用落地提供更多选择。