1. 项目概述为什么需要本地LLM API最近两年大语言模型LLM的应用呈现爆发式增长。与直接调用云端API相比本地部署的LLM具有三大不可替代的优势数据隐私性强所有计算在本地完成、使用成本低无需按token付费、响应速度快无网络延迟。本教程将带你从零开始用Python构建一个完全运行在本地的LLM API服务。这个项目特别适合以下场景处理敏感数据医疗/金融记录需要高频调用的自动化流程网络条件受限的环境希望完全掌控模型行为的开发者2. 环境准备与工具选型2.1 硬件需求分析虽然LLM可以在普通笔记本运行但推荐配置内存至少16GB7B参数模型最低要求显卡NVIDIA GPU显存≥8GB可流畅运行13B模型存储SSD硬盘模型文件通常20-100GB实测数据CPU推理7B模型约2-5 tokens/秒i7-12700HGPU推理同模型可达20-50 tokens/秒RTX 30602.2 软件栈选择我们的技术栈组合经过多次验证核心工具链 - Ollama模型管理工具→ 比直接使用transformers更易部署 - FastAPIWeb框架→ 比Flask更适合异步API - UvicornASGI服务器→ 支持HTTP/WebSocket重要提示务必使用Python 3.10版本旧版本可能遇到依赖冲突3. 分步实现指南3.1 模型部署实战首先安装Ollama以Ubuntu为例curl -fsSL https://ollama.com/install.sh | sh ollama pull llama2 # 下载7B参数的Llama2基础版启动模型服务ollama serve # 默认监听11434端口测试模型是否就绪import requests response requests.post( http://localhost:11434/api/generate, json{model: llama2, prompt: Hello} ) print(response.json())3.2 API服务搭建创建FastAPI应用app.pyfrom fastapi import FastAPI from pydantic import BaseModel app FastAPI() class Query(BaseModel): prompt: str max_tokens: int 128 app.post(/ask) async def ask_llm(query: Query): response requests.post( http://localhost:11434/api/generate, json{ model: llama2, prompt: query.prompt, max_tokens: query.max_tokens } ) return {answer: response.json()[response]}启动服务uvicorn app:app --reload --port 80004. 高级功能扩展4.1 流式响应实现修改API端点支持实时输出app.post(/ask_stream) async def ask_llm_stream(query: Query): def generate(): with requests.post( http://localhost:11434/api/generate, json{model: llama2, prompt: query.prompt}, streamTrue ) as r: for chunk in r.iter_content(): yield chunk.decode() return StreamingResponse(generate())4.2 性能优化技巧通过以下配置提升吞吐量# 在Ollama启动时添加参数 OLLAMA_NUM_PARALLEL4 ollama serve # FastAPI中间件配置 app.add_middleware( GZipMiddleware, minimum_size1000 )5. 生产环境注意事项5.1 安全加固方案必须添加的基础防护# API密钥验证中间件 API_KEYS {your-secret-key} app.middleware(http) async def auth_middleware(request: Request, call_next): if request.url.path.startswith(/ask): if request.headers.get(x-api-key) not in API_KEYS: raise HTTPException(status_code403) return await call_next(request)5.2 监控与日志推荐监控指标请求延迟P99应1sToken生成速度GPU显存占用率日志配置示例import logging logging.basicConfig( filenamellm_api.log, levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s )6. 常见问题排错指南问题现象可能原因解决方案返回乱码编码错误检查response.json()的解析逻辑GPU未利用CUDA未配置安装对应版本的cudatoolkit响应超时显存不足换用更小模型或减少max_tokens安装失败Python版本冲突使用conda创建虚拟环境我在实际部署中发现最大的性能瓶颈往往是显存带宽而非计算能力。当处理长文本时可以尝试以下技巧使用--numa参数绑定NUMA节点启用flash_attention优化对输入文本先做分块处理