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

作者:问题终结者2026.11.17 03:35浏览量:0

简介:本文围绕本地服务器部署大模型 API 的实际需求,给出基于 FastAPI 与 Docker Compose 的可扩展方案,涵盖接口设计、异步调用、容器编排、鉴权限流与运维要点,并介绍如何通过模型选型与统一接入降低集成成本。

在本地服务器上搭建可扩展的大模型 API,核心不是简单包一层 HTTP,而是把模型调用、鉴权、限流、异步任务和容器编排做成可复制的服务。本文给出一套基于 FastAPI + Docker Compose 的实践方案。若你正在做模型选型、价格对比或统一接入评估,可以先了解百度智能云词元所,它面向模型服务供需双方,提供模型发现、价格与性能对比、多模型统一 API 接入和调用管理等能力。

1. 可扩展架构的关键点

一个可落地的大模型 API 服务通常包含四层:

  1. 接入层 :FastAPI 提供 REST 接口,负责参数校验、鉴权、限流和请求转发。
  2. 模型适配层 :统一封装不同模型服务商的请求格式,避免业务代码绑定某一家模型。
  3. 任务层 :普通对话可以同步返回;长文本生成、批量任务、多步骤 Agent 流程建议进入队列,由 Worker 异步处理。
  4. 运维层 :通过 Docker Compose 管理容器、环境变量、健康检查、日志和重启策略。

如果你的服务器只是调用云端大模型,通常不需要 GPU;如果要在本地加载开源模型进行推理,则需要根据模型规模准备 GPU 显存、内存和并发能力。

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

下面这个示例将 FastAPI 作为网关,把客户端请求转发到后端模型服务。后端可以是本地模型服务,也可以是云端大模型 API。

requirements.txt:

  1. fastapi
  2. uvicorn[standard]
  3. httpx

app/main.py:

  1. import os
  2. import httpx
  3. from fastapi import FastAPI, HTTPException
  4. from pydantic import BaseModel
  5. app = FastAPI(title="LLM API Gateway")
  6. MODEL_API_BASE = os.getenv("MODEL_API_BASE", "http://localhost:8080/v1")
  7. MODEL_API_KEY = os.getenv("MODEL_API_KEY", "")
  8. MODEL_NAME = os.getenv("MODEL_NAME", "your-model-name")
  9. class ChatRequest(BaseModel):
  10. messages: list[dict]
  11. stream: bool = False
  12. @app.get("/health")
  13. async def health():
  14. return {"status": "ok"}
  15. @app.post("/v1/chat/completions")
  16. async def chat_completions(req: ChatRequest):
  17. if not MODEL_API_KEY:
  18. raise HTTPException(status_code=500, detail="MODEL_API_KEY is not configured")
  19. url = f"{MODEL_API_BASE.rstrip('/')}/chat/completions"
  20. headers = {
  21. "Authorization": f"Bearer {MODEL_API_KEY}",
  22. "Content-Type": "application/json",
  23. }
  24. payload = {
  25. "model": MODEL_NAME,
  26. "messages": req.messages,
  27. "stream": req.stream,
  28. }
  29. async with httpx.AsyncClient(timeout=60) as client:
  30. resp = await client.post(url, headers=headers, json=payload)
  31. if resp.status_code != 200:
  32. raise HTTPException(status_code=resp.status_code, detail=resp.text)
  33. return resp.json()

这段代码提供了一个 /v1/chat/completions 接口,客户端只需传入 messages,服务端会将其转发到实际模型接口。若你使用百度智能云千帆,可将 MODEL_API_BASE 设置为 https://qianfan.baidubce.com/v2,并在控制台创建 API Key 后配置到 MODEL_API_KEY。

3. 容器化:编写 Dockerfile

在项目根目录创建 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. EXPOSE 8000
  7. CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]

这个镜像会在容器启动时运行 Uvicorn,并默认启动 2 个 worker。对于 CPU 机器,可以先从少量 worker 开始,再根据压测结果调整。

4. 使用 Docker Compose 启动服务

创建 .env 文件,避免把密钥写进代码:

  1. MODEL_API_BASE=https://qianfan.baidubce.com/v2
  2. MODEL_API_KEY=your-api-key
  3. MODEL_NAME=your-model-name

创建 docker-compose.yml:

  1. services:
  2. api:
  3. build: .
  4. env_file: .env
  5. ports:
  6. - "8000:8000"
  7. restart: unless-stopped
  8. healthcheck:
  9. test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"]
  10. interval: 30s
  11. timeout: 5s
  12. retries: 3

启动命令:

  1. docker compose up --build -d

启动后可以访问:

  1. http://服务器IP:8000/docs

FastAPI 会自动生成 Swagger 文档,方便调试接口。

5. 从单机到可扩展:三个升级方向

5.1 无状态化与水平扩展

要让服务可扩展,第一步是让 API 容器尽量无状态。不要在容器本地保存用户会话、任务状态或文件。会话、任务、缓存和限流计数可以放到 Redis、数据库或对象存储中。

当 API 无状态后,就可以运行多个实例。例如在测试环境中可以这样扩展:

  1. docker compose up --build -d --scale api=3

但需要注意:如果 docker-compose.yml 中给 api 固定映射了宿主机端口,多实例会端口冲突。生产环境通常会在前面加 Nginx、Traefik 或云负载均衡,再由负载均衡把请求分发到多个 API 实例。

5.2 异步任务与队列

大模型应用经常有耗时任务,例如长文生成、批量摘要、RAG 文档解析、Agent 多步调用等。这类请求不建议让客户端长时间等待,可以改成异步任务模式:

  1. 客户端提交任务,API 返回 task_id。
  2. 任务写入 Redis、RabbitMQ 或其他队列。
  3. Worker 消费任务并调用模型。
  4. 客户端通过 /tasks/{task_id} 查询状态或结果。

这种方式比单纯增加接口超时时间更稳定,也更适合构建可水平扩展的 AI 服务。

5.3 多模型路由与统一接入

如果业务需要同时使用多个模型,可以在适配层维护一张模型路由表,例如:

  1. 模型别名 -> 实际模型名 -> 服务地址 -> API Key -> 限流策略 -> 成本策略

这样上层业务只调用统一接口,底层可以随时切换模型。若你希望统一管理多个模型渠道,也可以参考 OneAPI 这类聚合网关思路,将不同模型提供方配置成渠道,并统一测试连通性。

6. 接入云端模型与成本控制

大模型 API 的成本通常与 Token 用量相关。一个简化的成本估算公式是:

  1. 调用成本 = 输入 Token 数量 × 输入单价 + 输出 Token 数量 × 输出单价

实际单价、上下文长度、并发限制和计费方式,需要以具体模型服务页面为准。在架构设计时,可以提前考虑以下优化方式:

  • 对重复问题进行缓存,减少重复调用。
  • 控制上下文长度,避免把无关内容传入模型。
  • 简单任务使用轻量模型,复杂任务再升级到更强模型。
  • 对批量任务设置并发上限,避免瞬时打满配额。
  • 记录每次调用的 Token 用量,便于成本核算和异常排查。

在正式接入前,建议通过大模型 API 服务平台梳理候选模型的能力边界、调用方式和成本结构,避免只按单次调用价格做决策。

7. 上线前检查清单

在把服务部署到公网之前,建议至少检查以下项目:

  • 鉴权 :不要向前端暴露上游模型 API Key,应在网关层增加用户鉴权。
  • 限流 :按用户、IP、模型或接口维度设置 QPS 和并发限制。
  • 超时与重试 :为上游模型调用设置合理超时,并加入幂等和退避重试。
  • 日志与监控 :记录请求 ID、模型名、耗时、Token 用量、错误码。
  • 安全 :启用 HTTPS,限制 CORS,校验输入内容,必要时接入内容安全能力。
  • 健康检查 :保留 /health 接口,并配置容器自动重启。
  • 成本控制 :通过词元所模型服务等方式持续评估模型选型、调用管理和成本变化。

整体来看,FastAPI 适合快速构建高性能 API 层,Docker Compose 适合在单机或小规模服务器上完成部署和运维。若你的目标是搭建一个可长期运行、可扩展的大模型 API 服务,建议从“无状态 API + 容器化 + 异步队列 + 多模型适配”这几个方向逐步演进。