利用 API 调用大模型：Ollama 实战指南

1. 引言

随着大语言模型（LLM）的普及，开发者越来越多地需要通过 API 来集成和调用模型能力。Ollama 作为一个轻量级、开源的工具，能够帮助开发者在本地或服务器上轻松部署和管理大模型，并通过简洁的 API 提供调用服务。本文将详细介绍如何利用 Ollama 的 API 来调用大模型，涵盖从环境准备到实际调用的完整流程。

2. Ollama 简介与安装

Ollama 是一个用于在本地运行大语言模型的工具，它支持多种开源模型（如 Llama 2、Mistral、CodeLlama 等），并提供了 RESTful API 和命令行接口，方便开发者集成。

2.1 安装 Ollama

访问 Ollama 官网（Ollama）下载对应操作系统的安装包，或使用命令行安装：

# macOS / Linux curl -fsSL https://ollama.com/install.sh | sh Windows (通过 Winget) winget install ollama.ollama

安装完成后，启动 Ollama 服务：

ollama serve

2.2 拉取模型

Ollama 安装后，需要拉取想要使用的模型。例如，拉取 DeepSeek-R1 7B 模型：

ollama pull deepseek-r1:7b

可以通过ollama list查看已下载的模型列表。

3. Ollama API 基础

Ollama 默认在http://localhost:11434提供 API 服务。主要端点包括：

• /api/generate：用于文本生成。
• /api/chat：用于多轮对话。
• /api/tags：获取可用模型列表。
• /api/show：获取模型详细信息。

4. 通过 API 调用大模型

4.1 文本生成（/api/generate）

使用/api/generate端点进行单次文本补全。以下是一个使用curl的示例：

curl http://localhost:11434/api/generate -d '{ "model": "deepseek-r1:7b", "prompt": "请用一句话解释人工智能。", "stream": false }'

如果您想使用 Python 直接运行，可以使用以下代码：

import requests import json # Ollama 【单轮补全接口】，和之前 /api/chat 是两套接口 url = "http://localhost:11434/api/generate" payload = { "model": "deepseek-r1:7b", # 使用本地已下载模型 "prompt": "请用一句话解释人工智能。", # 直接填写完整提示词 "stream": False # 关闭流式输出，等待全部生成完一次性返回 } try: # 发送POST请求 response = requests.post(url, json=payload) response.raise_for_status() # HTTP状态码非200则抛出异常 result = response.json() # 字符串转为字典 # ⭐重点：generate接口返回内容key叫 response print("🤖 模型回复：", result.get("response", "无回复内容")) print("📊 生成统计：") print(f" - 总耗时: {result.get('total_duration', 0) / 1_000_000_000:.2f}秒") print(f" - 生成token数: {result.get('eval_count', 0)}") except requests.exceptions.ConnectionError: print("❌ 连接失败：请确保 Ollama 服务已启动（运行 ollama serve）") except requests.exceptions.RequestException as e: print(f"❌ 请求错误：{e}") except json.JSONDecodeError: print("❌ JSON解析失败：服务器返回了非JSON格式的响应")

4.1.1 代码功能解析

这个示例展示了如何使用 Python 调用 Ollama 的/api/generate端点。代码中：

• 接口地址：指定了 Ollama 的文本生成端点/api/generate
• 模型选择：使用deepseek-r1:7b，这是一个响应速度较快的轻量级模型
• 提示词设计：设置了明确的提示词，要求模型用一句话解释人工智能
• 流式控制：关闭了流式输出（stream: false），等待完整响应
• 错误处理：添加了全面的错误处理，包括连接错误、请求异常和JSON解析错误
• 响应解析：正确解析返回的 JSON 响应，response字段包含了模型的生成结果
• 性能统计：展示了生成统计信息，如总耗时和生成的token数

4.1.2 关键参数说明

• model：必需参数，指定要使用的模型名称
• prompt：必需参数，输入给模型的提示词文本
• stream：可选参数，控制是否使用流式输出。设置为false时等待完整响应，设置为true时逐token返回
• temperature：可选参数，控制输出的随机性（0.0-1.0），值越高输出越随机
• top_p：可选参数，核采样参数，影响词汇选择的集中度
• num_predict：可选参数，限制生成的最大 token 数

4.1.3 运行前准备

运行此代码前，请确保：

1. Ollama 服务已启动（ollama serve）
2. 已下载所需模型（ollama pull deepseek-r1:7b）
3. Python 环境中已安装requests库（pip install requests）

4.1.4 实际应用场景

/api/generate端点适用于以下场景：

• 文本补全：根据给定的提示词生成后续文本
• 代码生成：根据需求描述生成代码片段
• 内容创作：生成文章、诗歌、故事等创意内容
• 翻译任务：将文本从一种语言翻译到另一种语言
• 摘要提取：从长文本中提取关键信息摘要

4.2 对话聊天（/api/chat）

对于多轮对话场景，使用/api/chat端点。请求需要传递消息历史：

curl http://localhost:11434/api/chat -d '{ "model": "deepseek-r1:7b", "messages": [ { "role": "user", "content": "你好，请介绍一下你自己。" } ], "stream": false }'

如果您想使用 Python 直接运行，可以使用以下代码：

# 导入网络请求库，用来发送HTTP请求访问ollama接口 import requests # 导入json工具库（这里代码里没直接用到，接口会自动序列化） import json # Ollama 本地聊天接口地址 url = "http://localhost:11434/api/chat" # 请求体，遵循Ollama官方api规范 payload = { "model": "deepseek-r1:7b", # 指定本地已经拉取好的模型名称 "messages": [ # 历史对话上下文列表 {"role": "user", "content": "你好，请介绍一下你自己。"}, # 用户第一轮提问 {"role": "assistant", "content": "我是DeepSeek-R1，一个由深度求索公司开发的大型语言模型。"}, # AI上一轮回答 {"role": "user", "content": "你能帮我做什么？"} # 用户最新问题 ], "stream": False # 关键参数：False=一次性返回完整结果；True=流式逐字推送（打字机效果） } try: # 向ollama服务发送POST请求，自动把payload转为json response = requests.post(url, json=payload) # 如果返回状态码不是200（连接成功），直接抛出异常进入catch response.raise_for_status() # 将接口返回的字符串转为python字典，方便读取内容 result = response.json() # 解析模型返回的消息 if "message" in result: message = result["message"] print(f"💬 {message.get('role', 'assistant')}: {message.get('content', '')}") else: print("🤖 模型回复：", result.get("message", {}).get("content", "无回复内容")) # Ollama接口自带性能统计信息 print("📊 对话统计：") # payload里3条历史消息 + AI本次新回复，所以+1 print(f" - 消息总数: {len(payload['messages']) + 1}") # total_duration单位是纳秒，除以 10^9 换算成秒 print(f" - 总耗时: {result.get('total_duration', 0) / 1_000_000_000:.2f}秒") # eval_count：本次生成输出的token数量 print(f" - 生成token数: {result.get('eval_count', 0)}") # 异常捕获区域 except requests.exceptions.ConnectionError: # 无法连接11434端口，ollama程序没启动 print("❌ 连接失败：请确保 Ollama 服务已启动（运行 ollama serve）") except requests.exceptions.RequestException as e: # 通用网络请求异常 print(f"❌ 请求错误：{e}") except json.JSONDecodeError: # ollama返回的数据格式错乱，无法转json print("❌ JSON解析失败：服务器返回了非JSON格式的响应")

4.2.1 代码功能解析

这个示例展示了如何使用 Python 调用 Ollama 的/api/chat端点。代码中：

• 接口地址：指定了 Ollama 的对话聊天端点/api/chat
• 模型选择：使用deepseek-r1:7b，支持多轮对话的上下文理解
• 消息历史：设置了完整的消息数组，包含多轮对话历史（用户-助手-用户）
• 流式控制：关闭了流式输出（stream: false），等待完整响应
• 错误处理：添加了全面的错误处理，包括连接错误、请求异常和JSON解析错误
• 响应解析：正确解析返回的 JSON 响应，message字段包含了模型的回复内容
• 对话统计：展示了对话统计信息，包括消息总数和生成耗时

4.2.2 关键参数说明

• model：必需参数，指定要使用的模型名称
• messages：必需参数，消息历史列表，格式为[{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]
• stream：可选参数，控制是否使用流式输出。设置为false时等待完整响应，设置为true时逐token返回
• temperature：可选参数，控制输出的随机性（0.0-1.0）
• top_p：可选参数，核采样参数，影响词汇选择的集中度
• num_predict：可选参数，限制生成的最大 token 数

4.2.3 消息格式详解

消息数组中的每个消息对象包含以下字段：

• role：消息角色，可以是"user"（用户）、"assistant"（助手）或"system"（系统）
• content：消息内容，即对话文本

消息历史的管理策略：

1. 上下文窗口：模型有固定的上下文长度限制，需要合理管理历史消息
2. 系统提示：可以在消息数组开头添加{"role": "system", "content": "..."}来设置系统指令
3. 历史截断：当对话历史过长时，需要截断或总结早期对话内容

4.2.4 运行前准备

运行此代码前，请确保：

1. Ollama 服务已启动（ollama serve）
2. 已下载所需模型（ollama pull deepseek-r1:7b）
3. Python 环境中已安装requests库（pip install requests）

4.2.5 实际应用场景

/api/chat端点适用于以下场景：

• 智能客服：处理用户咨询和问题解答
• 编程助手：提供代码编写、调试和优化建议
• 学习辅导：回答学习问题，提供知识讲解
• 创意对话：进行开放式的创意对话和头脑风暴
• 任务规划：协助制定计划和分解复杂任务

5. 高级配置与参数调优

Ollama API 支持多种参数来调整生成效果：

• temperature：控制输出的随机性（0.0-1.0）。
• top_p：核采样参数，影响词汇选择的集中度。
• num_predict：限制生成的最大 token 数。

示例：在请求中加入这些参数：

{ "model": "deepseek-r1:7b", "prompt": "写一首关于春天的诗。", "temperature": 0.7, "top_p": 0.9, "num_predict": 100, "stream": false }

6. 常见问题与排查

6.1 服务未启动

确保 Ollama 服务正在运行：ollama serve。

6.2 模型未下载

使用ollama pull <model-name>下载所需模型。

6.3 端口冲突

默认端口 11434 被占用时，可通过环境变量OLLAMA_HOST修改。

7. 总结

Ollama 为开发者提供了一个极其便捷的本地大模型调用方案。通过其清晰的 REST API，我们可以轻松地将大模型能力集成到各种应用中。本文介绍了从安装、基础 API 调用到 Python 集成和参数调优的完整流程，希望能帮助你快速上手利用 Ollama API 调用大模型。