把大模型真正跑在自己电脑上，这件事两年前还像是玩家的玩具，但放到现在，已经是一件非常正经的生产力工具了。最近我把内网的一个问答机器人彻底重构了一遍，后端用 FastAPI 封装服务，模型运行时统一走 Ollama，核心收益非常直接：不连外网、按 token 计费的成本问题直接归零、所有对话数据完全留在本地。同事们试完都在问，这东西是不是一个“私有版 ChatGPT”。如果你手头有一张 6GB 以上显存的显卡，或者一台 16GB 内存的普通机器，这套 FastAPI+Ollama 的组合完全能让你在半天之内把本地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.5b | 1.5B | 约 1.1GB | 2GB | 简单问答、文本分类、低配机器 |
| qwen2.5:7b | 7B | 约 4.7GB | 6GB | 中文对话、摘要、翻译，性价比最高 |
| deepseek-r1:7b | 7B（蒸馏） | 约 4.7GB | 6-8GB | 数学、逻辑推理、代码 |
| llama3.1:8b | 8B | 约 4.9GB | 8GB | 英文场景、通用任务 |
| qwen2.5:14b | 14B | 约 9GB | 12-16GB | 要求更高推理质量的场景 |
| deepseek-r1:14b | 14B（蒸馏） | 约 9GB | 12-16GB | 复杂代码、深度推理 |
选型逻辑很直接：显存不够，模型部分层会落到内存里跑，速度慢到让人崩溃。所以 8GB 显存的卡，老老实实选 7B 量化版；16GB 以上可以考虑 14B；32GB 以上再研究 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_length=1, description="用户输入") history: list[ChatMessage] = Field(default_factory=list, description="历史消息") model: Optional[str] = None temperature: float = Field(default=0.7, ge=0.0, le=2.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(timeout=httpx.Timeout(REQUEST_TIMEOUT)) as client: if not stream: resp = await client.post(f"{OLLAMA_BASE_URL}/api/chat", json=payload) resp.raise_for_status() return resp.json() async with client.stream("POST", f"{OLLAMA_BASE_URL}/api/chat", json=payload) 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 f"data: {json.dumps({'content': content}, ensure_ascii=False)}\n\n" yield "data: [DONE]\n\n" return StreamingResponse(event_generator(), media_type="text/event-stream")最后在 main.py 挂载路由和跨域配置：
# app/main.py from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from app.routers import chat app = FastAPI(title="Local 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_URL=http://你的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] Description=Chat Assistant API After=network.target [Service] User=youruser WorkingDirectory=/opt/chat-assistant ExecStart=/home/youruser/miniconda3/envs/chat/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 Restart=always RestartSec=3 Environment=OLLAMA_BASE_URL=http://127.0.0.1:11434 [Install] WantedBy=multi-user.targetOllama 侧也有几个重要的环境变量：
| 环境变量 | 作用 | 我的推荐值 |
|---|---|---|
| OLLAMA_HOST | 监听地址 | 0.0.0.0:11434（局域网访问） |
| OLLAMA_KEEP_ALIVE | 模型在内存中驻留时间 | 30m 或 24h，避免频繁加载 |
| OLLAMA_NUM_GPU | 模型加载到 GPU 的层数 | 999 表示尽量全上 GPU |
| OLLAMA_MODELS | 模型存储路径 | 放在空间大的磁盘分区 |
设置方式是在启动 Ollama 前导入环境变量，比如：
export OLLAMA_HOST=0.0.0.0:11434 export OLLAMA_KEEP_ALIVE=24h 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, temperature=0.7, stream=True): 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_HOST=0.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，性能和稳定性都会好很多。这也是我最后重构时采用的拓扑。
如果你要在现有项目里把 FastAPI+Ollama 这套再往深了扩展，我个人觉得最值得投入的方向是接一个本地知识库：用向量数据库存文档切片，查询时先检索再交给大模型总结，这样对话助手就不再是“什么都懂但什么都不精”的通用模型，而是真正懂你们团队业务资料的内行助理。具体的向量库选型、Embedding 模型选择、检索链路设计，那又是另一个可以写一整篇的话题了。先把对话服务稳定跑起来，后面的路自然就清楚了。
