FastAPI+Ollama本地部署大模型：从选型到流式对话的完整实践指南

把大模型真正跑在自己电脑上这件事两年前还像是玩家的玩具但放到现在已经是一件非常正经的生产力工具了。最近我把内网的一个问答机器人彻底重构了一遍后端用 FastAPI 封装服务模型运行时统一走 Ollama核心收益非常直接不连外网、按 token 计费的成本问题直接归零、所有对话数据完全留在本地。同事们试完都在问这东西是不是一个“私有版 ChatGPT”。如果你手头有一张 6GB 以上显存的显卡或者一台 16GB 内存的普通机器这套 FastAPIOllama 的组合完全能让你在半天之内把本地AI大模型对话助手跑起来而且每一步都是可以复现的。这篇文章就把我完整走过一遍的部署过程、接口设计、模型选型和踩坑记录全部摊开讲适合刚接触本地大模型部署的开发者也适合想把自己项目快速接上大模型能力的团队参考。1. 先说清楚这套方案到底解决什么问题很多人在本地跑大模型第一反应是直接用 HuggingFace 的 transformers 加载权重再拿 Flask 起一个 HTTP 服务。这个路子能跑通但维护成本很高模型格式要选量化要自己处理显卡显存不够还得折腾 CPU offload会话管理、并发请求、参数调优全都要自己写。我用过一阵子之后果断换成了 Ollama说实话像把一个需要自己组装发动机的车换成了直接拧钥匙就能走的车。Ollama 做的事其实很纯粹把大模型的下载、存储、运行、对外接口全部封装好。它底层调用 llama.cpp 那套推理引擎支持 GGUF 格式的量化模型默认监听 11434 端口提供本地 REST API而且这个 API 是 OpenAI 兼容的。这意味着你写业务的代码时根本不用关心模型权重在显存里怎么排布、KV Cache 怎么分配只需要按它的接口规范发请求就行。对绝大多数应用场景来说这就够了。FastAPI 的定位同样清晰。它是一个异步 Web 框架天然支持 Pydantic 做请求体校验自带 OpenAPI 文档更关键的是 StreamingResponse 做流式输出非常方便。做过大模型应用的人应该深有体会用户对着聊天框等三秒钟才出第一个字和半秒内就看到文字一个接一个蹦出来完全是两个体验。而流式响应恰恰是 FastAPI 的强项配合 async 的 HTTP 客户端请求 Ollama整条链路可以做到全异步不阻塞事件循环。选 Flask 也能做但需要额外处理线程问题和流式响应的边界控制不如 FastAPI 顺手。这套方案的典型用户画像大概是三类一是自己做 side project 的开发者想快速给应用塞一个能对话的 AI 功能二是中小企业内部要做知识库问答或办公助手数据不能出内网三是在校学生和研究者想在有限硬件条件下做大模型应用的实验。反过来如果你要做高并发、服务成千上万用户的商用产品那本地单机 Ollama 不是正确答案应该直接考虑分布式推理框架或云上 API这个后面我会专门提一句。1.1 选型背后的三个理由第一个理由是好组合。Ollama 把“模型运行时”这件事做到开箱即用FastAPI 把“业务服务层”做到结构清晰两者用 HTTP 协议解耦。你随时可以把 Ollama 替换成 vLLM、LocalAI 等其他推理后端只要接口兼容业务代码几乎不用动。第二个理由是资源可控。本地模型不像云端 API 那样按 token 计费也没有并发数和频次限制。模型跑在自己机器上想调 temperature 就调想换模型就换模型想记录全部对话日志就记录。这种掌控感对做内部工具来说太重要了。第三个理由是数据安全。企业内部对话助手难免会碰到合同摘要、代码审查、内部流程咨询这类内容数据只要出了内网法务和合规都会找上门。本地部署直接把这个风险消掉了模型跑在内网机器上数据和日志全部落在自己的硬盘里。1.2 不适合用这套方案的情况也要泼一盆冷水。如果你期望的是 ChatGPT 那种综合性能力本地模型目前还有差距。7B 到 14B 量级的模型日常问答、翻译、写代码片段、Dubug 都够用但在长文本深度推理、复杂指令遵循等任务上体验确实不如商业大模型。另外单机方案的并发能力有限如果同一时间几十个人同时对话推理队列会明显变长。做内部工具可以接受做对外产品就要慎重。2. Ollama 部署安装、模型选型与下载提速2.1 安装与基础校验Ollama 官方提供了全平台安装包。Windows 和 macOS 直接去官网下载安装包双击就行它会自动注册成后台服务。Linux 服务器上更推荐用官方脚本安装curl -fsSL https://ollama.com/install.sh | sh装完之后先确认服务是否在跑ollama serve # 前台启动调试时用 ollama list # 查看已安装的模型 ollama ps # 查看当前加载在显存/内存里的模型默认情况下 Ollama 监听127.0.0.1:11434你可以在浏览器直接访问http://127.0.0.1:11434看到Ollama is running就说明基础服务没问题。在服务器部署时记得把监听地址改成0.0.0.0其他机器才能访问到这个后面说。拉取模型的命令很简单ollama pull qwen2.5:7b拉完用ollama run qwen2.5:7b就能在终端里直接聊两句先验证一下模型本身没问题再进入 FastAPI 开发环节。2.2 模型怎么选按硬件和场景来模型选型是整个方案里影响体验最大的一环。我的建议是不要盲目追求大参数要看你的显存和实际任务。下面这几种是我实际跑过且觉得稳定的组合模型参数规模量化后体积最低显存要求适用场景qwen2.5:1.5b1.5B约 1.1GB2GB简单问答、文本分类、低配机器qwen2.5:7b7B约 4.7GB6GB中文对话、摘要、翻译性价比最高deepseek-r1:7b7B蒸馏约 4.7GB6-8GB数学、逻辑推理、代码llama3.1:8b8B约 4.9GB8GB英文场景、通用任务qwen2.5:14b14B约 9GB12-16GB要求更高推理质量的场景deepseek-r1:14b14B蒸馏约 9GB12-16GB复杂代码、深度推理选型逻辑很直接显存不够模型部分层会落到内存里跑速度慢到让人崩溃。所以 8GB 显存的卡老老实实选 7B 量化版16GB 以上可以考虑 14B32GB 以上再研究 32B。另外要理解 GGUF 量化等级Q4_K_M 是通用推荐体积和效果最均衡Q8 效果更好但体积接近翻倍Q2 这种压缩太狠基本只适合跑在纯 CPU 的小机器上。日常使用认准 Q4_K_M 就够了。还有一个小经验如果机器同时跑多个模型Ollama 默认会把暂时不用的模型从显存卸载但频繁切换会反复加载反而更慢。所以生产环境最好是固定一到两个最常用的模型别贪多。2.3 下载慢的解决方案本地导入 GGUF很多人在ollama pull这一步就卡住了尤其是模型文件动辄几个 GB官方源下载速度经常让人崩溃。我个人的解决方案是不直接用ollama pull而是从国内的模型托管平台比如魔搭社区这类合规渠道下载 GGUF 格式的模型文件再本地导入。流程大概是这样的。先去模型托管平台搜索对应的 GGUF 文件比如下载qwen2.5-7b-instruct-q4_k_m.gguf存到本地某个目录。新建一个 Modelfile 文件内容很简单FROM ./qwen2.5-7b-instruct-q4_k_m.gguf然后执行导入命令ollama create qwen2.5:7b -f Modelfile跑完后用ollama list检查模型就在本地清单里了。这种方法的好处是下载走国内平台速度快得多而且 GGUF 文件本身就是 Ollama 的运行时格式不需要额外转换。需要注意一点同一个模型如果有多个量化版本挑体积在显存承受范围内的那个别只看文件名里的 Q4 字样。如果国内平台也找不到目标模型的 GGUF还有一个笨办法找一台网络好的机器先把官方模型 pull 下来然后把整个~/.ollama/models目录拷贝到目标机器。Ollama 模型本质上是分层存储的 blobs目录整体迁移后重新ollama list就能识别这是离线环境下很实用的做法。3. FastAPI 对话服务目录结构、接口设计与流式返回3.1 项目目录结构这样搭写 FastAPI 项目目录结构直接影响后续扩展。我目前的习惯是这样的chat-assistant/ ├── app/ │ ├── __init__.py │ ├── main.py # 应用入口注册路由和中间件 │ ├── config.py # 配置项模型名、超时、Ollama 地址 │ ├── routers/ │ │ ├── __init__.py │ │ └── chat.py # 对话相关接口 │ ├── services/ │ │ ├── __init__.py │ │ └── ollama_service.py # 封装 Ollama 请求逻辑 │ └── schemas/ │ ├── __init__.py │ └── chat.py # Pydantic 请求/响应模型 ├── requirements.txt ├── .env # 环境变量不入库 └── README.md这个结构把“接口层”和“服务层”分开。路由器负责参数校验和响应封装服务层负责和 Ollama 交互。以后如果要把 Ollama 换成其他推理后端只需要改 service 层接口不用动。很多初学者喜欢把所有逻辑堆在 main.py 里一个文件写几百行前期很爽后期改一个参数找半天强烈不建议。requirements.txt 里其实只需要几个核心依赖fastapi uvicorn httpx pydantic python-dotenv3.2 核心接口普通对话与流式返回先看配置模块简单直接# app/config.py import os from dotenv import load_dotenv load_dotenv() OLLAMA_BASE_URL os.getenv(OLLAMA_BASE_URL, http://127.0.0.1:11434) DEFAULT_MODEL os.getenv(DEFAULT_MODEL, qwen2.5:7b) REQUEST_TIMEOUT 600 # 单次推理最长等待时间 CONTEXT_WINDOW 4096 # 上下文窗口大小请求体用 Pydantic 定义# app/schemas/chat.py from pydantic import BaseModel, Field from typing import Optional class ChatMessage(BaseModel): role: str user content: str class ChatRequest(BaseModel): message: str Field(..., min_length1, description用户输入) history: list[ChatMessage] Field(default_factorylist, description历史消息) model: Optional[str] None temperature: float Field(default0.7, ge0.0, le2.0) stream: bool True服务层封装 Ollama 的调用。这里推荐用 httpx 而不是 requests因为 httpx 支持异步能直接配合 FastAPI 的异步机制而且它内置client.stream方法做流式转发非常自然# app/services/ollama_service.py import json import httpx from app.config import OLLAMA_BASE_URL, REQUEST_TIMEOUT async def chat_completion(messages: list, model: str, temperature: float 0.7, stream: bool True): payload { model: model, messages: messages, stream: stream, options: {temperature: temperature}, } async with httpx.AsyncClient(timeouthttpx.Timeout(REQUEST_TIMEOUT)) as client: if not stream: resp await client.post(f{OLLAMA_BASE_URL}/api/chat, jsonpayload) resp.raise_for_status() return resp.json() async with client.stream(POST, f{OLLAMA_BASE_URL}/api/chat, jsonpayload) as resp: resp.raise_for_status() async for line in resp.aiter_lines(): if line.strip(): yield json.loads(line)路由层把请求组装成 OpenAI messages 格式转发给 Ollama# app/routers/chat.py import json from fastapi import APIRouter, HTTPException from fastapi.responses import StreamingResponse from app.schemas.chat import ChatRequest from app.services import ollama_service from app.config import DEFAULT_MODEL router APIRouter(prefix/api, tags[chat]) router.post(/chat) async def chat(req: ChatRequest): model req.model or DEFAULT_MODEL messages [{role: msg.role, content: msg.content} for msg in req.history] messages.append({role: user, content: req.message}) async def event_generator(): async for chunk in ollama_service.chat_completion(messages, model, req.temperature): content chunk.get(message, {}).get(content, ) if content: yield fdata: {json.dumps({content: content}, ensure_asciiFalse)}\n\n yield data: [DONE]\n\n return StreamingResponse(event_generator(), media_typetext/event-stream)最后在 main.py 挂载路由和跨域配置# app/main.py from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from app.routers import chat app FastAPI(titleLocal Chat Assistant API) app.add_middleware( CORSMiddleware, allow_origins[*], allow_methods[*], allow_headers[*], ) app.include_router(chat.router)启动服务uvicorn app.main:app --host 0.0.0.0 --port 8000用 curl 测试一下就知道了curl -N -X POST http://127.0.0.1:8000/api/chat \ -H Content-Type: application/json \ -d {message: 你好介绍一下你自己}3.3 为什么优先做流式我第一次接非流式接口时让页面等一个完整回答完整返回。回答稍微一长七八秒甚至十几秒都是常态用户早就以为页面卡死了。后来改成流式体验完全不同——模型每生成一个字就推给前端用户看到文字继续滚动心里就有底。这不只是体验问题从工程角度看流式还有两个实际好处。第一个好处是能解决 HTTP 超时问题。网关、代理服务器普遍有 60 到 120 秒的超时限制非流式的长回答很容易被中间层掐断而流式响应一旦建立连接持续有数据流动大部分超时判定都会失效。第二个好处是可控性强。你可以实时判断内容是否合规、是否偏离主题也可以在用户点击“停止生成”时中断流节省不必要的算力。这在纯非流式模式下很难优雅实现。前端拿到 SSE 格式的数据后按行解析data:前缀就行。用浏览器自带 fetch 就能接const response await fetch(/api/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ message: 你好, history: [] }), }); const reader response.body.getReader(); const decoder new TextDecoder(); while (true) { const { done, value } await reader.read(); if (done) break; const chunk decoder.decode(value, { stream: true }); // 按行拆解提取 data: 前缀后的 JSON }4. 对话助手的上下文管理与前端接入4.1 上下文窗口与滑动窗口很多人在本地部署后第一个困惑是模型怎么“记不住”前面说的话原因很简单大模型的上下文是有限的而且默认情况下 Ollama 的消息处理并不会帮你做复杂的记忆管理。你发多少条消息它会尽量全部塞进上下文一旦超过模型窗口上限最前面的内容就会被截断最早的对话记忆就丢了。我的做法是在应用层做一个滑动窗口。只保留最近的若干轮对话再结合一个字符数上限做兜底。比如最多保留 10 轮或者总长度不超过 3000 个 token 估算值。代码很简单def build_context(history: list, max_tokens: int 3000) - list: # history 按时间正序存放倒序截取最近 N 条 selected [] total_len 0 for msg in reversed(history): msg_len len(msg[content]) if total_len msg_len max_tokens * 3: # 粗略按中文 1 字 ~ 1 token 估算 break selected.append(msg) total_len msg_len selected.reverse() return selected这个办法简单但非常实用避免了上下文塞满导致模型答非所问。如果你需要更精细的 token 统计可以接 tiktoken 或者 llama.cpp 的 tokenizer但对 7B 模型来说粗略估算已经足够。另外一个细节是系统提示词。对话助手的“人设”应该放在 messages 列表的第一条role 为 system比如{role: system, content: 你是一个专业的技术助手回答尽量简洁使用中文。}这个 system prompt 会占用上下文窗口但能显著提升回答的稳定性和风格一致性值得做。如果要调 Ollama 的 num_ctx也可以通过 Modelfile 或接口参数设置默认 2048 对很多模型来说偏小我通常调到 4096 或 8192前提是显存够用。4.2 前端接入自写页面和现成方案自己写前端是最灵活的一个 HTML 文件加几十行 JavaScript 就够。核心逻辑就是提交消息、读取 SSE 流、把返回内容追加到对话区域。如果不想重复造轮子更省事的方案是直接用现成的开源 Web 界面。目前比较成熟的是 Open WebUI它支持直接对接 Ollama界面和主流商业产品很像还内置知识库上传、多用户管理等功能。部署也很简单docker run -d -p 3000:8080 \ -v open-webui:/app/backend/data \ -e OLLAMA_BASE_URLhttp://你的Ollama地址:11434 \ ghcr.io/open-webui/open-webui:main还有一个轻量选择是 AnythingLLM它对 Ollama 的支持同样很好主要特色是内置工作区概念适合做文档问答和团队内部知识管理。如果你只是想快速演示给同事看部署一个 WebUI 容器十分钟就能搞完比自己写前端省事得多。需要注意的是这些 WebUI 默认通过浏览器直连 Ollama 的方式通信在局域网内部署问题不大但如果服务暴露到公网务必用 FastAPI 这套服务做一层鉴权和转发绝不能让 Ollama 的 11434 端口直接暴露。5. 部署上线与性能调优5.1 常驻服务与启动配置开发时uvicorn app.main:app前台运行没问题但生产环境要考虑开机自启和崩溃恢复。Linux 上用 systemd 管理最省心[Unit] DescriptionChat Assistant API Afternetwork.target [Service] Useryouruser WorkingDirectory/opt/chat-assistant ExecStart/home/youruser/miniconda3/envs/chat/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 Restartalways RestartSec3 EnvironmentOLLAMA_BASE_URLhttp://127.0.0.1:11434 [Install] WantedBymulti-user.targetOllama 侧也有几个重要的环境变量环境变量作用我的推荐值OLLAMA_HOST监听地址0.0.0.0:11434局域网访问OLLAMA_KEEP_ALIVE模型在内存中驻留时间30m 或 24h避免频繁加载OLLAMA_NUM_GPU模型加载到 GPU 的层数999 表示尽量全上 GPUOLLAMA_MODELS模型存储路径放在空间大的磁盘分区设置方式是在启动 Ollama 前导入环境变量比如export OLLAMA_HOST0.0.0.0:11434 export OLLAMA_KEEP_ALIVE24h ollama serveOLLAMA_KEEP_ALIVE 是我觉得最容易被忽略但是在实际体验中差异很大的一项。默认值下模型如果在几分钟内没有被调用Ollama 就会把模型从显存卸载下次请求又要重新加载冷启动等待有时候长达几十秒。设成 24h 后模型常驻显存响应基本秒回。代价是显存一直被占用不能再跑其他大任务这个要按机器用途权衡。5.2 并发、超时与显存监控本地单机方案的并发能力是有限的尤其是一块消费级显卡。我实测下来7B 模型 Q4 量化单次流式响应大概每秒生成 30 到 50 个 token也就是说生成 500 字的中文回答大约需要 10 到 20 秒。如果同时来三个请求推理引擎会排队总耗时直线上升。所以 FastAPI 这层要做两件事一是设置合理的超时避免某个请求卡死拖垮整个服务二是控制并发避免把推理引擎压垮。我目前的方案是给 httpx 客户端设置总超时 600 秒同时在服务端用一个简单的信号量限制同时进行的推理任务数量import asyncio semaphore asyncio.Semaphore(2) async def chat_completion(messages, model, temperature0.7, streamTrue): async with semaphore: # 原有逻辑 pass这样同一时间最多两个请求进入推理其他的排队等待页面端通过流式输出能够感知到“正在排队”的状态。监控方面不用搞太复杂ollama ps就能看到当前的显存占用和模型加载情况ollama ps # NAME ID SIZE PROCESSOR UNTIL # qwen2.5:7b abc123 5.2GB 100% GPU 24h如果想做图形化监控nvidia-smi 看显存占用率就已经够用了。有一点要特别提醒Ollama 的显存占用不等于模型文件大小它是模型权重加 KV Cache 的总和。上下文窗口调大KV Cache 会显著增长显存不够时进程可能直接 OOM这时候要么调小 num_ctx要么换更小量化的模型。6. 常见问题排查实录这些坑我替你们踩过了6.1 问题速查表把我实际踩过的坑包括网上问得最多的问题整理成一个速查表症状可能原因解决办法回答速度极慢每秒一两字模型没完全加载到 GPU部分层在 CPU 推理检查 OLLAMA_NUM_GPU 设置或换更小量化模型第一次请求等待十几秒模型冷启动OLLAMA_KEEP_ALIVE 太小设为 24h让模型驻留显存ollama pull 一直卡住或超时官方源网络不稳定用国内平台下载 GGUF 后 ollama create 导入流式接口返回到一半断掉前端或网关超时或者客户端主动断开确认请求方没有设置过短超时服务端关掉代理超时限制对话超过几轮后答非所问上下文窗口被暴力截断应用层做滑动窗口 截断历史局域网其他机器访问不了Ollama 或 uvicorn 只监听了 127.0.0.1设置 OLLAMA_HOST0.0.0.0启动 uvicorn 加 --host 0.0.0.0显存明明够用却提示 OOM上下文窗口 num_ctx 过大导致 KV Cache 膨胀调小 num_ctx或使用更小量化模型端口 11434 被占用其他程序占用了端口换端口并同步修改 FastAPI 里的 OLLAMA_BASE_URL模型回答内容风格不稳定没有设定系统提示词在 messages 首条加 role: system 的人设指令6.2 几个我想特别提醒的细节第一个细节是流式响应的数据格式问题。Ollama 的/api/chat流式接口返回的是 JSON Lines 格式每一行一个 JSON 对象我用代码里已经处理过了。但你如果直接用 OpenAI SDK 连接 Ollama 的 OpenAI 兼容端点http://127.0.0.1:11434/v1返回格式会略有差异解析方式也不同。我建议二选一不要混用自己的 FastAPI 服务统一走/api/chat外部工具统一走/v1。第二个细节是模型文件的备份。Ollama 的模型存储在~/.ollama/models目录下里面是一堆哈希命名的 blobs。如果你重新拉模型或者升级 Ollama 版本时出了问题整个目录的迁移和备份是唯一的后悔药。尤其是好不容易从国内平台导入成功的 GGUF 模型我建议直接压缩一份放到别的盘里别嫌占空间重下一次的痛大家应该都懂。第三个细节是版本兼容。Ollama 更新频率不算低大版本升级后有些旧模型格式可能无法加载或者 API 字段有调整。生产环境不要盲目升级先看更新日志在测试机验证后再动主服务。我遇到过升级后原本正常的 Modelfile 参数失效的情况来回排查浪费了一下午。还有一个经验不要把 Ollama 服务和 FastAPI 服务部署在同一台机器上的理由只考虑省机器。它们确实可以合在一起但如果推理时 CPU 和内存资源被其他任务抢占生成速度会很不稳定。有条件的话Ollama 单独一台带 GPU 的机器FastAPI 放另一台普通服务器中间走内网 HTTP性能和稳定性都会好很多。这也是我最后重构时采用的拓扑。如果你要在现有项目里把 FastAPIOllama 这套再往深了扩展我个人觉得最值得投入的方向是接一个本地知识库用向量数据库存文档切片查询时先检索再交给大模型总结这样对话助手就不再是“什么都懂但什么都不精”的通用模型而是真正懂你们团队业务资料的内行助理。具体的向量库选型、Embedding 模型选择、检索链路设计那又是另一个可以写一整篇的话题了。先把对话服务稳定跑起来后面的路自然就清楚了。