# 使用 FastAPI 和 Ollama 构建本地 LLM API 服务：零成本实现大模型推理 > 一个基于 FastAPI 和 Ollama 的开源项目，展示如何在本地部署大语言模型并通过 REST API 提供服务，无需调用付费 API，支持多轮对话、图像描述、文本分类等功能。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-06-08T22:41:34.000Z - 最近活动: 2026-06-08T22:48:34.356Z - 热度: 159.9 - 关键词: FastAPI, Ollama, 本地大模型, LLM API, Qwen2.5, Python, 开源项目, 私有化部署 - 页面链接: https://www.zingnex.cn/forum/thread/fastapi-ollama-llm-api - Canonical: https://www.zingnex.cn/forum/thread/fastapi-ollama-llm-api - Markdown 来源: ingested_event --- ## 原作者与来源 - **原作者/维护者**: sfc38 - **来源平台**: GitHub - **原始标题**: local-llm-api - **原始链接**: https://github.com/sfc38/local-llm-api - **发布时间**: 2026年6月8日 --- ## 背景：为什么需要本地 LLM API？ 随着大语言模型（LLM）技术的普及，越来越多的开发者希望在自己的应用中集成 AI 能力。然而，依赖第三方 API 服务往往意味着持续的费用支出、网络延迟以及数据隐私方面的顾虑。 本地部署 LLM 成为了一种极具吸引力的替代方案。通过在本地运行模型，开发者可以完全掌控数据流向，避免敏感信息泄露，同时摆脱对云端服务的依赖。但本地部署的门槛并不低——需要处理模型加载、推理优化、API 封装等复杂问题。 这就是 local-llm-api 项目的价值所在。它提供了一个开箱即用的解决方案，让开发者能够在几分钟内搭建起功能完整的本地 LLM 服务。 --- ## 项目概述：FastAPI meets Ollama local-llm-api 是一个基于 Python FastAPI 框架的开源项目，核心目标是简化本地大语言模型的 API 化过程。项目采用 Ollama 作为底层模型运行引擎，默认集成阿里通义千问的 Qwen2.5-VL 3B 模型，这是一个轻量级但功能强大的多模态模型。 项目的设计理念非常清晰：提供一套干净、易用的 REST API，让开发者无需关心底层模型加载和推理的复杂性，只需通过简单的 HTTP 请求就能调用 AI 能力。 技术栈全部选用开源且商业友好的组件：FastAPI（MIT 协议）、Uvicorn（BSD 协议）、Ollama（MIT 协议）、Qwen2.5-VL（Apache 2.0 协议）、Streamlit（Apache 2.0 协议）。这意味着你可以放心地将这套方案用于商业项目。 --- ## 核心功能详解 项目提供了七个主要 API 端点，覆盖了常见的 LLM 应用场景： ### 1. 健康检查端点（/health） 用于验证 API 服务和 Ollama 后端是否正常运行。这在生产环境中尤为重要，可以作为负载均衡器或服务监控系统的探针。 ### 2. 多轮对话（/chat） 支持带记忆的多轮对话。与单次生成不同，这个端点会维护完整的对话历史，让模型能够基于上下文理解用户意图。例如，用户先说"我的名字是 Alice"，再问"我叫什么"，模型能够正确回答。 ### 3. 单次生成（/generate） 最基础的文本生成接口，支持传入提示词、温度参数（temperature）、最大 token 数等控制选项。温度参数允许调节输出的创造性——较低值产生更确定性的回答，较高值则更具创造性。 ### 4. 图像描述（/describe-image） 利用 Qwen2.5-VL 的多模态能力，接收 base64 编码的图像并返回描述文本。这为视觉理解应用提供了基础能力，可用于图像标注、内容审核等场景。 ### 5. 文本摘要（/summarize） 专门用于长文本摘要的优化端点。对于需要处理大量文档的应用场景，这个端点提供了开箱即用的解决方案。 ### 6. 文本分类（/classify） 支持将文本分类到预定义的类别中。开发者只需提供类别列表，模型就会返回最匹配的类别。这在内容分类、情感分析等场景中非常实用。 ### 7. 关键词提取（/extract-keywords） 自动从文本中提取关键术语，可用于标签生成、搜索引擎优化、文档索引等应用。 --- ## 高级特性：不仅仅是基础 API 除了核心功能外，项目还实现了多项实用的高级特性： **流式响应（SSE）**：通过 Server-Sent Events 技术实现实时流式输出，让用户无需等待完整响应生成，提升交互体验。 **模型动态切换**：每个请求都可以通过 model 参数覆盖默认模型，支持在同一服务中灵活使用不同模型处理不同任务。 **完整的参数控制**：提供 temperature、max_tokens、top_p、top_k、repeat_penalty、seed、num_ctx 等丰富的生成参数，满足精细化的输出控制需求。 **请求日志记录**：自动将请求记录到 SQLite 数据库和日志文件，便于后续分析和审计。 **Streamlit 可视化界面**：除了 API，项目还提供了一个基于 Streamlit 的浏览器界面，支持 PDF 和图像附件上传，方便非技术人员测试和使用。 **Docker 支持**：提供 Dockerfile，可以一键构建容器化服务，简化部署流程。 --- ## 快速上手指南 使用这个项目非常简单，只需几个步骤： 首先确保已安装 Python 3.10+ 和 Ollama（建议从官网下载而非 Homebrew）。然后拉取 Qwen2.5-VL 3B 模型： ```bash ollama pull qwen2.5vl:3b ``` 克隆项目并安装依赖： ```bash git clone https://github.com/sfc38/local-llm-api.git cd local-llm-api python -m venv venv source venv/bin/activate pip install -r requirements.txt ``` 启动 API 服务： ```bash uvicorn app.main:app --reload ``` 现在可以访问 http://127.0.0.1:8000/docs 查看自动生成的 Swagger UI 文档，或者直接使用 curl 测试： ```bash curl -X POST http://127.0.0.1:8000/generate \ -H "Content-Type: application/json" \ -d '{"prompt": "解释什么是 RAG", "temperature": 0.5, "max_tokens": 200}' ``` --- ## 应用场景与价值 这个项目适合多种使用场景： **企业内部工具**：在私有网络中部署，处理敏感文档而不担心数据外泄。 **开发测试环境**：在调用付费 API 之前，先用本地模型进行原型验证。 **边缘计算场景**：在资源受限的环境中运行轻量级模型，无需依赖云端。 **学习与研究**：通过阅读源码学习 FastAPI 设计、LLM 集成和 API 开发最佳实践。 **定制化 AI 服务**：基于这个框架扩展自己的业务逻辑，构建垂直领域的 AI 应用。 --- ## 项目架构与代码组织 代码结构清晰，遵循现代 Python 项目最佳实践： - `app/main.py`：FastAPI 应用主入口，包含路由定义、日志配置、错误处理和 CORS 设置 - `app/config.py`：环境变量配置管理 - `app/schemas.py`：Pydantic 请求模型定义 - `app/ollama_client.py`：可复用的异步 HTTP 客户端，封装与 Ollama 的通信 - `app/services.py`：提示词模板和 SSE 流式响应处理 - `tests/test_api.py`：集成测试套件 - `streamlit_app.py`：浏览器界面实现 这种模块化设计使得代码易于理解和扩展。开发者可以方便地添加新的端点、修改提示词模板或集成其他模型后端。 --- ## 局限与未来展望 项目 README 中坦诚地列出了当前局限和未来改进方向： **计划中的功能**：Oracle Cloud 部署指南、对话历史限制（上下文窗口截断）、文件上传端点（PDF、txt 自动摘要）、速率限制、API 密钥认证支持。 这些规划显示出项目维护者对生产环境需求的深刻理解。特别是认证和速率限制的规划，表明这个项目正在向企业级应用演进。 --- ## 总结与建议 local-llm-api 是一个设计精良、文档完善的开源项目，成功降低了本地 LLM 部署的门槛。它不仅仅是一个简单的 API 包装器，而是提供了一套完整的解决方案，包括多模态支持、流式响应、可视化界面和容器化部署。 对于希望探索本地 LLM 应用的开发者来说，这是一个极佳的起点。项目代码质量高、结构清晰，非常适合作为学习材料或二次开发的基础。 如果你正在寻找一种零成本、私有化、可定制的大语言模型服务方案，local-llm-api 绝对值得一试。