简介:本文围绕本地服务器部署大模型 API 的实际需求,给出基于 FastAPI 与 Docker Compose 的可扩展方案,涵盖接口设计、异步调用、容器编排、鉴权限流与运维要点,并介绍如何通过模型选型与统一接入降低集成成本。
在本地服务器上搭建可扩展的大模型 API,核心不是简单包一层 HTTP,而是把模型调用、鉴权、限流、异步任务和容器编排做成可复制的服务。本文给出一套基于 FastAPI + Docker Compose 的实践方案。若你正在做模型选型、价格对比或统一接入评估,可以先了解百度智能云词元所,它面向模型服务供需双方,提供模型发现、价格与性能对比、多模型统一 API 接入和调用管理等能力。
一个可落地的大模型 API 服务通常包含四层:
如果你的服务器只是调用云端大模型,通常不需要 GPU;如果要在本地加载开源模型进行推理,则需要根据模型规模准备 GPU 显存、内存和并发能力。
下面这个示例将 FastAPI 作为网关,把客户端请求转发到后端模型服务。后端可以是本地模型服务,也可以是云端大模型 API。
requirements.txt:
fastapiuvicorn[standard]httpx
app/main.py:
import osimport httpxfrom fastapi import FastAPI, HTTPExceptionfrom pydantic import BaseModelapp = FastAPI(title="LLM API Gateway")MODEL_API_BASE = os.getenv("MODEL_API_BASE", "http://localhost:8080/v1")MODEL_API_KEY = os.getenv("MODEL_API_KEY", "")MODEL_NAME = os.getenv("MODEL_NAME", "your-model-name")class ChatRequest(BaseModel):messages: list[dict]stream: bool = False@app.get("/health")async def health():return {"status": "ok"}@app.post("/v1/chat/completions")async def chat_completions(req: ChatRequest):if not MODEL_API_KEY:raise HTTPException(status_code=500, detail="MODEL_API_KEY is not configured")url = f"{MODEL_API_BASE.rstrip('/')}/chat/completions"headers = {"Authorization": f"Bearer {MODEL_API_KEY}","Content-Type": "application/json",}payload = {"model": MODEL_NAME,"messages": req.messages,"stream": req.stream,}async with httpx.AsyncClient(timeout=60) as client:resp = await client.post(url, headers=headers, json=payload)if resp.status_code != 200:raise HTTPException(status_code=resp.status_code, detail=resp.text)return resp.json()
这段代码提供了一个 /v1/chat/completions 接口,客户端只需传入 messages,服务端会将其转发到实际模型接口。若你使用百度智能云千帆,可将 MODEL_API_BASE 设置为 https://qianfan.baidubce.com/v2,并在控制台创建 API Key 后配置到 MODEL_API_KEY。
在项目根目录创建 Dockerfile:
FROM python:3.11-slimWORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txtCOPY app ./appEXPOSE 8000CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]
这个镜像会在容器启动时运行 Uvicorn,并默认启动 2 个 worker。对于 CPU 机器,可以先从少量 worker 开始,再根据压测结果调整。
创建 .env 文件,避免把密钥写进代码:
MODEL_API_BASE=https://qianfan.baidubce.com/v2MODEL_API_KEY=your-api-keyMODEL_NAME=your-model-name
创建 docker-compose.yml:
services:api:build: .env_file: .envports:- "8000:8000"restart: unless-stoppedhealthcheck:test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"]interval: 30stimeout: 5sretries: 3
启动命令:
docker compose up --build -d
启动后可以访问:
http://服务器IP:8000/docs
FastAPI 会自动生成 Swagger 文档,方便调试接口。
要让服务可扩展,第一步是让 API 容器尽量无状态。不要在容器本地保存用户会话、任务状态或文件。会话、任务、缓存和限流计数可以放到 Redis、数据库或对象存储中。
当 API 无状态后,就可以运行多个实例。例如在测试环境中可以这样扩展:
docker compose up --build -d --scale api=3
但需要注意:如果 docker-compose.yml 中给 api 固定映射了宿主机端口,多实例会端口冲突。生产环境通常会在前面加 Nginx、Traefik 或云负载均衡,再由负载均衡把请求分发到多个 API 实例。
大模型应用经常有耗时任务,例如长文生成、批量摘要、RAG 文档解析、Agent 多步调用等。这类请求不建议让客户端长时间等待,可以改成异步任务模式:
task_id。/tasks/{task_id} 查询状态或结果。这种方式比单纯增加接口超时时间更稳定,也更适合构建可水平扩展的 AI 服务。
如果业务需要同时使用多个模型,可以在适配层维护一张模型路由表,例如:
模型别名 -> 实际模型名 -> 服务地址 -> API Key -> 限流策略 -> 成本策略
这样上层业务只调用统一接口,底层可以随时切换模型。若你希望统一管理多个模型渠道,也可以参考 OneAPI 这类聚合网关思路,将不同模型提供方配置成渠道,并统一测试连通性。
大模型 API 的成本通常与 Token 用量相关。一个简化的成本估算公式是:
调用成本 = 输入 Token 数量 × 输入单价 + 输出 Token 数量 × 输出单价
实际单价、上下文长度、并发限制和计费方式,需要以具体模型服务页面为准。在架构设计时,可以提前考虑以下优化方式:
在正式接入前,建议通过大模型 API 服务平台梳理候选模型的能力边界、调用方式和成本结构,避免只按单次调用价格做决策。
在把服务部署到公网之前,建议至少检查以下项目:
/health 接口,并配置容器自动重启。整体来看,FastAPI 适合快速构建高性能 API 层,Docker Compose 适合在单机或小规模服务器上完成部署和运维。若你的目标是搭建一个可长期运行、可扩展的大模型 API 服务,建议从“无状态 API + 容器化 + 异步队列 + 多模型适配”这几个方向逐步演进。