当前位置：首页 > news >正文

Cogito 3B部署教程：Ollama API对接FastAPI，打造企业级AI服务接口

news 2026/5/12 20:48:37

Cogito 3B部署教程：Ollama API对接FastAPI，打造企业级AI服务接口

你是不是也想在自己的服务器上部署一个强大的AI模型，然后通过一个标准的API接口来调用它？比如，你想开发一个智能客服系统，或者一个内容创作助手，但不想依赖第三方服务，希望数据完全掌握在自己手里。

今天，我就带你一步步实现这个目标。我们将使用一个性能非常出色的开源模型——Cogito 3B，通过Ollama来运行它，再用FastAPI给它套上一个标准、高效的Web API外壳。整个过程就像给一台强大的发动机（Cogito模型）装上方向盘和油门（Ollama），再给它造一个漂亮、好用的驾驶舱（FastAPI接口）。

学完这篇教程，你将拥有一个完全由自己掌控、可以7x24小时稳定运行的企业级AI服务接口。无论是集成到你的网站、APP，还是内部办公系统，都变得轻而易举。

1. 为什么选择Cogito 3B + Ollama + FastAPI？

在开始动手之前，我们先快速了解一下这套技术组合的优势，让你明白为什么这么选。

1.1 认识我们的核心：Cogito 3B模型

Cogito v1预览版模型，特别是我们今天要部署的cogito-v1-preview-llama-3B，是个“小而美”的狠角色。

性能强劲：在大多数标准测试中，它的表现都超过了同级别（3B参数规模）的其他知名开源模型，比如LLaMA、DeepSeek和Qwen的同类模型。这意味着用更小的资源，你能获得不错的智能水平。
功能独特：它是一个“混合推理”模型。简单说，它有两种模式：
- 标准模式：像普通聊天模型一样，直接回答问题。
- 推理模式：在回答前会先“自我反思”一下，像人一样多想想，适合解决更复杂、需要逻辑思考的问题。
实用性强：专门针对编程、科学计算、指令理解和通用问答做了优化，还支持超过30种语言和长达128K的上下文。对于大多数企业应用场景，比如代码辅助、知识问答、多语言客服，它都游刃有余。
完全开源：允许商业使用，没有后顾之忧。

1.2 强大的模型运行器：Ollama

Ollama就像一个专为大型语言模型设计的“播放器”。它的好处是：

一键部署：通过简单的命令就能拉取和运行各种模型，管理起来非常方便。
提供标准API：Ollama本身自带了一个RESTful API（默认在11434端口），我们可以直接通过HTTP请求和模型对话。这为我们后续封装打下了基础。
资源友好：对CPU和GPU资源的管理比较高效，特别适合在服务器上长期运行。

1.3 高效的API框架：FastAPI

FastAPI是Python领域构建API的“当红炸子鸡”，我们用它来封装Ollama的API，理由如下：

开发极快：用很少的代码就能构建出功能完整的API。
自动文档：它会自动生成漂亮的交互式API文档（Swagger UI），前端同事或者你自己测试的时候会爱死这个功能。
性能卓越：基于Starlette和Pydantic，速度非常快，能轻松应对高并发请求。
类型安全：利用Python的类型提示，减少错误，代码更清晰。

简单比喻：Cogito 3B是发动机，Ollama是传动系统和底盘，FastAPI就是那个拥有仪表盘、方向盘和空调的驾驶舱。接下来，我们开始组装这辆“车”。

2. 环境准备与Ollama部署

首先，我们需要一台Linux服务器（Ubuntu 20.04/22.04或CentOS 7/8为例），并确保有Python 3.8+的环境。假设你已经通过SSH连接上了你的服务器。

2.1 安装Ollama

Ollama的安装非常简单，一行命令搞定。

# 在终端中执行以下命令下载并安装Ollama curl -fsSL https://ollama.com/install.sh | sh

安装完成后，Ollama服务会自动启动。你可以用下面的命令检查状态：

# 检查Ollama服务状态 sudo systemctl status ollama

如果看到active (running)的字样，说明服务已经跑起来了。

2.2 拉取并运行Cogito 3B模型

Ollama安装好，接下来就是把我们的“发动机”——Cogito 3B模型下载下来。

# 从Ollama的模型库中拉取cogito:3b模型 ollama pull cogito:3b

这个命令会从网络下载模型文件，根据你的网速，可能需要几分钟到十几分钟。下载完成后，你就可以直接运行这个模型了：

# 在命令行中与cogito:3b模型交互（类似聊天） ollama run cogito:3b

运行后，你会看到一个提示符>>>，这时你可以直接输入问题，比如“用Python写一个快速排序函数”，模型就会生成回答。按Ctrl+D可以退出这个交互模式。

到这里，模型已经在本地运行起来了。但我们的目标是通过API调用，所以先让它在后台运行。

# 让模型在后台以API服务模式运行 ollama serve & # 或者使用nohup让它更稳定地在后台运行 # nohup ollama serve > ollama.log 2>&1 &

默认情况下，Ollama的API服务运行在http://localhost:11434。你可以快速测试一下：

# 测试Ollama API是否正常工作 curl http://localhost:11434/api/tags

如果返回一个JSON，里面列出了你拉取的模型（包括cogito:3b），说明API服务一切正常。

3. 构建FastAPI应用，封装企业级接口

现在“发动机”和“底盘”准备好了，我们来打造“驾驶舱”。我们将创建一个Python项目，用FastAPI提供更规范、更安全的API。

3.1 创建项目并安装依赖

首先，为我们的API服务创建一个新的目录，并设置虚拟环境（推荐，可以隔离依赖）。

# 创建项目目录并进入 mkdir cogito_fastapi_service && cd cogito_fastapi_service # 创建虚拟环境（假设使用python3） python3 -m venv venv # 激活虚拟环境 source venv/bin/activate # Linux/macOS # 如果是Windows，使用：venv\Scripts\activate # 安装必要的Python包 pip install fastapi uvicorn httpx python-dotenv

fastapi: 我们的Web框架。
uvicorn: 一个轻量级的ASGI服务器，用于运行FastAPI应用。
httpx: 一个现代化的HTTP客户端，我们将用它来调用后端的Ollama API。
python-dotenv: 用于从.env文件加载环境变量，方便配置管理。

3.2 设计API接口与编写核心代码

我们的目标是提供两个最核心的接口：

/v1/chat/completions(模仿OpenAI格式)：接收用户消息，返回模型生成的回复。
/health：健康检查接口，用于监控服务是否存活。

在项目根目录下，创建两个文件：.env和main.py。

首先，创建.env文件来管理配置：

# .env 配置文件 OLLAMA_BASE_URL=http://localhost:11434 OLLAMA_MODEL=cogito:3b API_HOST=0.0.0.0 API_PORT=8000

然后，创建主程序文件main.py：

# main.py import os from typing import List, Optional from fastapi import FastAPI, HTTPException from pydantic import BaseModel, Field import httpx from dotenv import load_dotenv import logging # 加载环境变量 load_dotenv() # 配置日志 logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) # 从环境变量读取配置 OLLAMA_BASE_URL = os.getenv("OLLAMA_BASE_URL", "http://localhost:11434") OLLAMA_MODEL = os.getenv("OLLAMA_MODEL", "cogito:3b") API_HOST = os.getenv("API_HOST", "0.0.0.0") API_PORT = int(os.getenv("API_PORT", 8000)) # 初始化FastAPI应用 app = FastAPI( title="Cogito 3B API Service", description="基于Ollama和FastAPI封装的企业级Cogito 3B模型API服务", version="1.0.0" ) # 初始化HTTP客户端，保持连接池以提高性能 client = httpx.AsyncClient(timeout=60.0) # 超时时间设为60秒 # ---------- 数据模型定义 (Request/Response Schema) ---------- class Message(BaseModel): """单条消息""" role: str = Field(..., description="消息角色，如 'user', 'assistant', 'system'") content: str = Field(..., description="消息内容") class ChatCompletionRequest(BaseModel): """聊天补全请求体 (模仿OpenAI格式)""" model: Optional[str] = Field(default=OLLAMA_MODEL, description="使用的模型，默认为配置的模型") messages: List[Message] = Field(..., description="消息历史列表") stream: Optional[bool] = Field(default=False, description="是否使用流式输出") max_tokens: Optional[int] = Field(default=2048, description="生成的最大token数") class ChatCompletionChoice(BaseModel): """聊天补全选项""" index: int = 0 message: Message finish_reason: Optional[str] = "stop" class ChatCompletionResponse(BaseModel): """聊天补全响应体 (模仿OpenAI格式)""" id: str = "chatcmpl-" # 简单模拟一个ID object: str = "chat.completion" created: int = 0 # 时间戳可以后续填充 model: str = OLLAMA_MODEL choices: List[ChatCompletionChoice] usage: Optional[dict] = {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0} # ---------- 核心API端点 ---------- @app.post("/v1/chat/completions", response_model=ChatCompletionResponse) async def create_chat_completion(request: ChatCompletionRequest): """ 核心聊天补全接口。 接收用户消息，调用后端Ollama服务，返回模型生成的回复。 """ logger.info(f"收到聊天请求，消息数：{len(request.messages)}") # 1. 准备发送给Ollama的请求数据 # 将消息列表转换为Ollama API所需的格式 prompt = "" for msg in request.messages: prompt += f"{msg.role}: {msg.content}\n" prompt += "assistant: " # 提示模型开始回复 ollama_payload = { "model": request.model or OLLAMA_MODEL, "prompt": prompt, "stream": request.stream, "options": { "num_predict": request.max_tokens # Ollama中使用num_predict参数 } } # 2. 调用Ollama API ollama_url = f"{OLLAMA_BASE_URL}/api/generate" try: logger.info(f"调用Ollama API: {ollama_url}") response = await client.post(ollama_url, json=ollama_payload) response.raise_for_status() # 如果状态码不是2xx，抛出异常 ollama_result = response.json() except httpx.RequestError as e: logger.error(f"请求Ollama API失败: {e}") raise HTTPException(status_code=503, detail=f"后端模型服务暂时不可用: {str(e)}") except httpx.HTTPStatusError as e: logger.error(f"Ollama API返回错误状态码: {e.response.status_code}") raise HTTPException(status_code=502, detail=f"后端模型服务错误: {e.response.text}") # 3. 处理Ollama的响应，并格式化成OpenAI兼容的格式 generated_text = ollama_result.get("response", "").strip() logger.info(f"模型生成完成，长度：{len(generated_text)}") # 构建返回给客户端的响应 assistant_message = Message(role="assistant", content=generated_text) choice = ChatCompletionChoice(message=assistant_message) return ChatCompletionResponse( choices=[choice], model=request.model or OLLAMA_MODEL ) @app.get("/health") async def health_check(): """ 健康检查端点。 用于监控服务是否正常运行，也可以简单测试Ollama后端是否连通。 """ try: # 简单检查Ollama是否可访问 async with httpx.AsyncClient() as test_client: resp = await test_client.get(f"{OLLAMA_BASE_URL}/api/tags", timeout=5.0) ollama_ok = resp.status_code == 200 except Exception: ollama_ok = False status = "healthy" if ollama_ok else "degraded" return { "status": status, "fastapi_service": "running", "ollama_backend": "available" if ollama_ok else "unavailable" } @app.on_event("shutdown") async def shutdown_event(): """应用关闭时，关闭HTTP客户端连接""" await client.aclose() logger.info("HTTP客户端连接已关闭") # ---------- 主程序入口 ---------- if __name__ == "__main__": import uvicorn logger.info(f"启动Cogito API服务，监听 {API_HOST}:{API_PORT}") uvicorn.run(app, host=API_HOST, port=API_PORT)

3.3 代码要点解析

这段代码虽然不长，但包含了构建一个健壮API服务的关键点：

配置管理：使用.env文件，将API地址、模型名称、端口等配置外部化，便于在不同环境（开发、测试、生产）部署。
结构化数据：使用Pydantic的BaseModel定义了清晰的请求和响应数据结构。这不仅能自动验证客户端传来的数据是否合法，还能让FastAPI自动生成漂亮的API文档。
错误处理：在调用Ollama API时，我们使用了try...except块来捕获网络错误和HTTP错误，并向上游客户端返回友好的错误信息（503服务不可用、502网关错误等），而不是直接抛出Python异常。
格式转换：我们将通用的OpenAI API格式的请求（messages列表），转换成了Ollama API所需的prompt字符串格式。同时，将Ollama的响应再包装成OpenAI兼容的格式返回。这样做的好处是，前端代码如果之前是调用ChatGPT API的，可以几乎无缝迁移到我们这个服务上。
健康检查：/health端点对于运维监控至关重要。它可以被Kubernetes、Docker Swarm或负载均衡器定期调用，以判断服务实例是否健康。
资源管理：使用httpx.AsyncClient并保持长连接，可以提高调用Ollama API的效率。在应用关闭时，我们优雅地关闭了这个客户端。

4. 启动服务与接口测试

代码写好了，让我们来启动它，并看看效果。

4.1 启动FastAPI服务

在你的项目目录下（虚拟环境已激活），运行：

# 启动FastAPI开发服务器 python main.py

你应该会看到类似下面的输出，说明服务已经启动在http://0.0.0.0:8000：

INFO:root:启动Cogito API服务，监听 0.0.0.0:8000 INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

4.2 测试API接口

服务跑起来了，我们通过几种方式来测试它。

方法一：使用自动生成的API文档（最方便）打开你的浏览器，访问http://你的服务器IP:8000/docs。你会看到一个Swagger UI界面，里面列出了我们刚写的两个接口。你可以直接在这个页面上点击“Try it out”，输入数据，然后点击“Execute”来测试/v1/chat/completions接口。

方法二：使用cURL命令测试打开另一个终端，用curl命令来测试：

# 1. 测试健康检查接口 curl http://localhost:8000/health # 2. 测试核心聊天接口 curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "messages": [ {"role": "user", "content": "请用简单的语言解释一下什么是人工智能？"} ], "max_tokens": 150 }'

如果一切正常，健康检查接口会返回{"status":"healthy", ...}，聊天接口会返回一个JSON，其中choices[0].message.content字段就是Cogito 3B模型生成的回答。

方法三：使用Python脚本测试创建一个test_client.py文件：

# test_client.py import httpx import asyncio async def test_chat(): async with httpx.AsyncClient() as client: response = await client.post( "http://localhost:8000/v1/chat/completions", json={ "messages": [{"role": "user", "content": "写一首关于春天的五言绝句。"}] } ) print("状态码:", response.status_code) print("响应JSON:", response.json()) if __name__ == "__main__": asyncio.run(test_chat())

运行python test_client.py，看看模型生成的唐诗怎么样。

5. 进阶配置与生产环境部署建议

到目前为止，一个可用的API服务已经搭建完成。但如果要用于真实的生产环境，还需要考虑更多。

5.1 配置优化与功能增强

你可以根据需求，修改main.py来增强服务：

增加身份验证（API Key）：在关键的/v1/chat/completions接口上添加依赖项，检查请求头中的Authorization字段。
支持流式响应（Streaming）：我们的代码中预留了stream参数。要真正支持流式输出，需要修改接口，使用FastAPI的StreamingResponse，并处理Ollama返回的流式数据块。这对于需要实时显示生成结果的场景（如聊天界面）很重要。
调整模型参数：在调用Ollama API的options里，可以加入更多参数，比如temperature（控制随机性）、top_p（核采样）等，来调整模型生成的效果。
添加请求限流（Rate Limiting）：使用像slowapi这样的中间件，防止API被滥用。
更详细的日志：记录每个请求的耗时、token使用量等，便于分析和计费。

5.2 生产环境部署

在开发服务器（python main.py）上运行没问题，但生产环境需要更稳定、性能更好的方式。

1. 使用Gunicorn/Uvicorn WorkerUvicorn本身是一个ASGI服务器，但在生产环境中，我们通常会在它前面再加一个进程管理器，比如Gunicorn。

# 安装gunicorn pip install gunicorn # 使用gunicorn启动服务，使用4个worker进程 gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 main:app

-w 4: 指定4个worker进程，可以根据你的CPU核心数调整。
-k uvicorn.workers.UvicornWorker: 指定使用Uvicorn worker来处理ASGI应用。
-b: 绑定地址和端口。
main:app: 指定应用对象，main是模块名，app是FastAPI实例名。

2. 使用进程守护与管理（Systemd）为了让服务在服务器重启后能自动运行，并且方便管理（启动、停止、重启、查看日志），最好配置成系统服务。

创建一个服务文件/etc/systemd/system/cogito-api.service：

[Unit] Description=Cogito 3B FastAPI Service After=network.target [Service] User=your_username # 改为你的系统用户名 Group=your_groupname # 改为你的用户组 WorkingDirectory=/path/to/your/cogito_fastapi_service # 改为你的项目绝对路径 Environment="PATH=/path/to/your/cogito_fastapi_service/venv/bin" # 虚拟环境路径 ExecStart=/path/to/your/cogito_fastapi_service/venv/bin/gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 main:app Restart=always RestartSec=10 [Install] WantedBy=multi-user.target

然后启用并启动服务：

sudo systemctl daemon-reload sudo systemctl enable cogito-api.service sudo systemctl start cogito-api.service # 查看状态和日志 sudo systemctl status cogito-api.service sudo journalctl -u cogito-api.service -f

3. 使用反向代理（Nginx）在生产环境中，通常不会让Gunicorn直接对外服务。我们会在前面加一个Nginx作为反向代理，它可以处理静态文件、负载均衡、SSL/TLS加密（HTTPS）等。

一个简单的Nginx配置片段 (/etc/nginx/sites-available/cogito-api)：

server { listen 80; server_name your_domain.com; # 你的域名或IP location / { proxy_pass http://127.0.0.1:8000; # 转发给Gunicorn proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 如果你有静态文件，可以在这里配置 # location /static { # alias /path/to/your/static/files; # } }

配置好后，重启Nginx即可。你还可以使用Let‘s Encrypt为你的域名申请免费SSL证书，配置HTTPS，让API调用更安全。