Ollama API 快速入门指南：解锁本地大模型的编程能力

引言

在本地运行大型语言模型（LLMs）已不再是遥不可及的事情。Ollama 的出现，让在个人电脑上安装、运行和管理各类开源模型变得前所未有的简单。然而，仅仅通过命令行与模型交互只是第一步。对于开发者、研究人员或任何希望将本地 LLMs 集成到自己的应用程序或工作流程中的用户来说，Ollama 提供的强大 API 才是真正解锁其潜力的关键。

本文将作为一份详尽的 Ollama API 快速入门指南，带你深入了解如何使用 Ollama API 进行文本生成、构建聊天应用、生成文本向量、管理模型等核心操作。无论你是 Python 开发者、Node.js 程序员，还是仅仅想通过 curl 命令体验一下 API 的威力，都能在这里找到你需要的信息。

为什么使用 Ollama API？

Ollama 提供 API 的主要目的是为了实现程序化交互。这意味着你可以通过编写代码来控制模型的行为、发送请求、接收响应，并将 LLM 的能力集成到更广泛的软件生态中。使用 Ollama API 的主要优势包括：

集成性： 将 LLMs 集成到你的网站、桌面应用、自动化脚本、数据分析流程等。
自动化： 批量处理文本、自动生成报告、构建智能客服机器人等。
灵活性： 精确控制模型的输入、参数（如温度、top_p 等），并处理流式或非流式响应。
隐私和安全： 数据和模型都在本地运行，无需将敏感信息发送到第三方服务。
成本效益： 一旦模型下载完成，后续使用主要消耗计算资源，没有按 token 计费的烦恼（除了硬件和电力成本）。
离线可用： 无需互联网连接即可使用 API（除非需要下载新模型）。

如果你希望构建一个基于本地 LLM 的应用，那么学习如何使用 Ollama API 是必经之路。

前置条件

在开始学习 Ollama API 之前，请确保你已完成以下准备工作：

安装 Ollama: 访问 Ollama 官方网站下载并安装适用于你操作系统的 Ollama。安装过程通常非常简单。
下载一个或多个模型: 安装完成后，打开终端或命令行界面，使用 ollama pull <model_name> 命令下载你感兴趣的模型。例如，下载 Llama 2 模型：
bash ollama pull llama2
你可以下载多个模型，如 mistral、codellama 等。使用 ollama list 命令可以查看已下载的模型列表。
确保 Ollama 服务正在运行: Ollama 安装后通常会作为后台服务自动运行，监听默认端口 11434。你可以在终端运行 ollama serve 来手动启动服务（如果它没有自动运行），或者在任务管理器/活动监视器中确认 ollama 进程正在运行。
基础编程知识: 本文将提供 Python 和 JavaScript 的代码示例，因此具备其中一种语言的基础知识将有助于你理解和实践。
了解 HTTP 请求: Ollama API 是一个 RESTful API，基于 HTTP 协议。理解 HTTP 请求方法（POST）、请求头（Content-Type）、请求体（JSON）和响应体（JSON）等基本概念会有帮助。

Ollama API 概览

Ollama API 默认运行在 http://localhost:11434 地址上。它提供了一系列端点（endpoints）来执行不同的任务。主要的核心端点包括：

POST /api/generate: 用于文本生成（Completion）。接收一个 Prompt，返回生成的文本。
POST /api/chat: 用于多轮对话（Chat）。接收一个包含消息历史的数组，返回模型的回复。
POST /api/embeddings: 用于生成文本的向量表示（Embeddings）。接收一个文本输入，返回对应的向量。
GET /api/tags: 列出本地已下载的所有模型。
POST /api/pull: 从 Ollama 注册表拉取一个模型。
DELETE /api/delete: 删除一个本地模型。
POST /api/create: 使用 Modelfile 创建一个自定义模型。
GET /api/show: 显示模型的详细信息，包括 Modelfile。
GET /api/version: 获取 Ollama 服务的版本信息。

本文主要关注最常用的 generate、chat、embeddings 和 tags 端点。

快速开始：使用 API

有多种方式可以与 Ollama API 交互。我们将重点介绍使用官方推荐的客户端库（Python 和 JavaScript）以及直接使用 curl 命令。

1. 使用 Python 客户端库 (`ollama-python`)

这是 Python 开发者与 Ollama API 交互的最推荐方式。它封装了底层的 HTTP 请求，提供了更 Pythonic 的接口。

安装客户端库:

bash pip install ollama

代码示例：

首先，导入库并创建一个客户端实例：

“`python
import ollama

创建一个 Ollama 客户端实例

默认连接到 http://localhost:11434

client = ollama.Client()

如果 Ollama 服务不在默认地址/端口，可以这样指定：

client = ollama.Client(host=’http://YOUR_OLLAMA_HOST:PORT’)

“`

1.1 文本生成 (`/api/generate`)

这是最基本的用法，给定一个 Prompt，模型生成一段文本来完成它。

非流式生成 (Blocking):

“`python

非流式生成

prompt = “告诉我一个关于人工智能的冷笑话。”
print(f”Prompt: {prompt}”)

try:
response = client.generate(model=’llama2′, prompt=prompt)
# response 是一个字典，包含生成的文本等信息
print(“\n— 非流式响应 —“)
print(response[‘response’])
# print(response) # 查看完整的响应结构
except ollama.ResponseError as e:
print(f”API Error: {e}”)
except Exception as e:
print(f”An error occurred: {e}”)

“`

流式生成 (Streaming):

对于更长的响应，或者在交互式应用中，流式生成可以提供更好的用户体验，文本会随着生成逐步返回。

“`python

流式生成

prompt = “详细描述一下大型语言模型（LLM）的工作原理，字数不少于300字。”
print(f”\nPrompt (Streaming): {prompt}”)
print(“\n— 流式响应 —“)

try:
stream = client.generate(model=’llama2′, prompt=prompt, stream=True)
# stream 是一个生成器，每次迭代返回一部分响应
for part in stream:
# 每个 part 也是一个字典，包含 ‘response’ 字段
print(part[‘response’], end=”, flush=True) # 使用 end=” 和 flush=True 实现连续打印
print(“\n— 流式响应结束 —“)
except ollama.ResponseError as e:
print(f”\nAPI Error: {e}”)
except Exception as e:
print(f”\nAn error occurred: {e}”)
“`

常用参数:

client.generate() 方法接受多个参数来控制生成行为：

model (str, 必需): 使用哪个模型进行生成（例如 'llama2'）。
prompt (str, 必需): 输入给模型的文本。
stream (bool, 可选): 是否以流式方式获取响应（默认为 False）。
options (dict, 可选): 一个包含生成选项的字典，例如：
- temperature (float): 控制随机性，值越高越随机（0.0 – 2.0），默认为 0.8。
- top_p (float): 控制采样范围，值越低越倾向于高概率 token（0.0 – 1.0），默认为 0.9.
- repeat_penalty (float): 控制重复惩罚，值越高越不容易重复相同 token（1.0 – 2.0），默认为 1.1.
- num_predict (int): 限制生成的 token 数量。
- seed (int): 指定随机种子以获得可重复的结果。
- 更多选项请参考 Ollama 文档或 /api/generate 接口说明。
system (str, 可选): 提供一个系统消息，用于指导模型整体行为（类似于聊天中的系统消息）。
template (str, 可选): 使用一个自定义模板来格式化 Prompt。

示例：使用 options 和 system 消息

“`python

使用 options 和 system 消息

prompt = “写一个关于未来城市的段落。”
system_message = “你是一个富有想象力的科幻作家，请用充满奇幻色彩的语言来描述。”
options = {
‘temperature’: 0.9,
‘top_p’: 0.7,
‘num_predict’: 200 # 限制生成大约200个token
}

print(f”\nPrompt: {prompt}\nSystem: {system_message}\nOptions: {options}”)
try:
response = client.generate(
model=’llama2′,
prompt=prompt,
system=system_message,
options=options
)
print(“\n— 定制生成响应 —“)
print(response[‘response’])
except ollama.ResponseError as e:
print(f”\nAPI Error: {e}”)
except Exception as e:
print(f”\nAn error occurred: {e}”)
“`

1.2 多轮对话 (`/api/chat`)

chat 端点更适合进行连续的多轮对话。它接收一个 messages 数组，数组中的每个元素代表一轮对话（用户或助手）。

基本对话:

“`python

多轮对话示例

messages = [
{‘role’: ‘system’, ‘content’: ‘你是一个乐于助人的AI助手。’},
{‘role’: ‘user’, ‘content’: ‘请告诉我今天的天气怎么样？’},
]

print(“\n— 首次聊天请求 —“)
try:
response = client.chat(model=’llama2′, messages=messages)
print(“Assistant:”, response[‘message’][‘content’])

# 添加助手的回复到 messages 列表，进行下一轮对话
messages.append(response['message'])
messages.append({'role': 'user', 'content': '那明天的呢？'})

print("\n--- 第二次聊天请求 ---")
response = client.chat(model='llama2', messages=messages)
print("Assistant:", response['message']['content'])

except ollama.ResponseError as e:
print(f”\nAPI Error: {e}”)
except Exception as e:
print(f”\nAn error occurred: {e}”)
“`

流式对话:

与 generate 类似，chat 也支持流式输出。

“`python

流式聊天示例

messages_streaming = [
{‘role’: ‘system’, ‘content’: ‘你是一个喜欢讲故事的AI。’},
{‘role’: ‘user’, ‘content’: ‘给我讲一个简短的冒险故事。’}
]

print(“\n— 流式聊天请求 —“)
try:
stream = client.chat(model=’llama2′, messages=messages_streaming, stream=True)
print(“Assistant (Streaming): “, end=”, flush=True)
for part in stream:
# 流式聊天的 part[‘message’] 包含 ‘content’ 字段
if ‘content’ in part[‘message’]:
print(part[‘message’][‘content’], end=”, flush=True)
print(“\n— 流式聊天结束 —“)
except ollama.ResponseError as e:
print(f”\nAPI Error: {e}”)
except Exception as e:
print(f”\nAn error occurred: {e}”)
“`

client.chat() 方法的参数：

model (str, 必需): 使用的模型。
messages (list of dict, 必需): 对话历史数组，每个字典至少包含 'role' (可以是 'system', 'user', 'assistant') 和 'content' 字段。
stream (bool, 可选): 是否流式输出（默认为 False）。
options (dict, 可选): 与 generate 类似的生成选项。

1.3 生成文本向量 (`/api/embeddings`)

embeddings 端点用于将文本转换成固定长度的数值向量。这些向量捕获了文本的语义信息，常用于文本相似度计算、搜索、聚类等任务（例如构建 RAG 系统）。需要注意的是，并非所有模型都支持生成 Embedding，通常需要专门训练或微调过的模型。像 nomic-embed-text 或一些支持 Embedding 的通用模型都可以。

“`python

生成 Embeddings

text1 = “大型语言模型在自然语言处理中有广泛应用。”
text2 = “自然语言处理（NLP）是人工智能的一个重要分支。”
text3 = “如何烤制一个美味的披萨？” # 语义上不相关的文本

注意：需要一个支持生成 embeddings 的模型。

例如，可以拉取 nomic-embed-text: `ollama pull nomic-embed-text`

embedding_model = ‘nomic-embed-text’ # 确保你已经拉取了这个模型

print(f”\n— 生成 Embeddings —“)
try:
embedding1 = client.embeddings(model=embedding_model, prompt=text1)
embedding2 = client.embeddings(model=embedding_model, prompt=text2)
embedding3 = client.embeddings(model=embedding_model, prompt=text3)

# embedding['embedding'] 包含向量列表
print(f"'{text1[:20]}...' Embedding 长度: {len(embedding1['embedding'])}")
print(f"'{text2[:20]}...' Embedding 长度: {len(embedding2['embedding'])}")
print(f"'{text3[:20]}...' Embedding 长度: {len(embedding3['embedding'])}")

# （可选）计算向量相似度（例如余弦相似度）
import numpy as np
from numpy.linalg import norm

def cosine_similarity(vec1, vec2):
    return np.dot(vec1, vec2) / (norm(vec1) * norm(vec2))

vec1 = np.array(embedding1['embedding'])
vec2 = np.array(embedding2['embedding'])
vec3 = np.array(embedding3['embedding'])

similarity12 = cosine_similarity(vec1, vec2)
similarity13 = cosine_similarity(vec1, vec3)

print(f"'{text1[:20]}...' 和 '{text2[:20]}...' 的余弦相似度: {similarity12:.4f}")
print(f"'{text1[:20]}...' 和 '{text3[:20]}...' 的余弦相似度: {similarity13:.4f}")

except ollama.ResponseError as e:
print(f”\nAPI Error: {e}”)
print(f”Hint: Make sure you have downloaded an embedding model like ‘{embedding_model}’ using ‘ollama pull {embedding_model}'”)
except Exception as e:
print(f”\nAn error occurred: {e}”)

“`

1.4 列出本地模型 (`/api/tags`)

你可以通过 API 查看本地已下载的模型列表。

“`python

列出本地模型

print(“\n— 本地模型列表 —“)
try:
models = client.list()
print(“已下载模型:”)
for model_info in models[‘models’]:
print(f”- {model_info[‘name’]} (大小: {model_info[‘size’] / (1024*1024):.2f} MB, 修改时间: {model_info[‘modified_at’]})”)
except ollama.ResponseError as e:
print(f”\nAPI Error: {e}”)
except Exception as e:
print(f”\nAn error occurred: {e}”)
“`

1.5 其他模型管理操作

客户端库也支持 create, pull, delete, show 等 API 端点对应的方法，用于更高级的模型管理。例如：

“`python

示例：拉取一个模型 (非阻塞，可以在后台运行 Ollama 命令或者使用 pull_stream 方法)

注意：这通常是一个耗时操作，建议在应用启动时或单独处理。

以下代码仅作演示，实际应用中需考虑用户界面反馈和错误处理。

try:

print(“\n— 尝试拉取新的模型 (非阻塞) —“)

# 这只是发起请求，下载在后台进行

pull_response = client.pull(model=’mistral’, stream=False)

print(f”拉取请求已发送: {pull_response}”)

except ollama.ResponseError as e:

print(f”\nAPI Error: {e}”)

except Exception as e:

print(f”\nAn error occurred: {e}”)

示例：删除一个模型

try:

print(“\n— 尝试删除模型 (假设存在一个名为 ‘test-model’ 的模型) —“)

# 谨慎操作，模型删除后无法恢复

# delete_response = client.delete(model=’test-model’)

# print(f”删除响应: {delete_response}”)

except ollama.ResponseError as e:

print(f”\nAPI Error: {e}”)

except Exception as e:

print(f”\nAn error occurred: {e}”)

示例：显示模型信息

try:
print(“\n— 查看模型信息 —“)
model_info = client.show(model=’llama2′)
print(f”模型 ‘{model_info[‘name’]}’ Modelfile:”)
print(model_info[‘modelfile’][:200] + ‘…’) # 打印前200字符
except ollama.ResponseError as e:
print(f”\nAPI Error: {e}”)
except Exception as e:
print(f”\nAn error occurred: {e}”)
“`

2. 使用 JavaScript / Node.js 客户端库 (`ollama`)

对于 Node.js 或前端（通过 fetch API 或打包工具）开发者，可以使用官方提供的 JavaScript 客户端库。

安装客户端库:

“`bash
npm install ollama

或 yarn add ollama

“`

代码示例：

首先，导入库：

javascript import ollama from 'ollama' // 或 const ollama = require('ollama') 在 CommonJS 环境中

2.1 文本生成 (`/api/generate`)

``javascript async function generateText() { const prompt = "写一个关于月球的俳句（五七五结构）。"; console.log(\nPrompt: ${prompt}`);

try {
// 非流式生成
const response = await ollama.generate({
model: ‘llama2’, // 确保你已下载此模型
prompt: prompt,
stream: false,
});
console.log(“\n— 非流式响应 —“);
console.log(response.response);

// 流式生成
console.log("\n--- 流式响应 ---");
const stream = await ollama.generate({
  model: 'llama2',
  prompt: "详细解释一下光合作用的过程。",
  stream: true,
});

process.stdout.write("Assistant (Streaming): ");
for await (const part of stream) {
  process.stdout.write(part.response);
}
process.stdout.write("\n--- 流式响应结束 ---\n");

} catch (error) {
console.error(“API Error:”, error);
console.error(“确保 Ollama 服务正在运行，并且模型 ‘llama2’ 已下载.”);
}
}

generateText();
“`

2.2 多轮对话 (`/api/chat`)

“`javascript
async function startChat() {
let messages = [
{ role: ‘system’, content: ‘你是一个友善的，热爱自然和动物的AI助手。’ },
{ role: ‘user’, content: ‘给我讲一个关于森林里小动物的故事。’ },
];

console.log(“\n— 首次聊天请求 —“);
try {
const response1 = await ollama.chat({
model: ‘llama2’,
messages: messages,
stream: false,
});
console.log(“Assistant:”, response1.message.content);

// 添加助手的回复，进行下一轮对话
messages.push(response1.message);
messages.push({ role: 'user', content: '故事里有小兔子吗？' });

console.log("\n--- 第二次聊天请求 ---");
const response2 = await ollama.chat({
  model: 'llama2',
  messages: messages,
  stream: false,
});
console.log("Assistant:", response2.message.content);

// 流式聊天示例
console.log("\n--- 流式聊天请求 ---");
 let messages_streaming = [
  { role: 'system', content: '你是一个喜欢用诗歌回复的AI。' },
  { role: 'user', content: '请用诗歌形式描述一下傍晚的景色。' },
];
const stream = await ollama.chat({
  model: 'llama2',
  messages: messages_streaming,
  stream: true,
});

process.stdout.write("Assistant (Streaming): ");
 for await (const part of stream) {
    if (part.message && part.message.content) {
         process.stdout.write(part.message.content);
    }
}
process.stdout.write("\n--- 流式聊天结束 ---\n");

} catch (error) {
console.error(“API Error:”, error);
console.error(“确保 Ollama 服务正在运行，并且模型 ‘llama2’ 已下载.”);
}
}

startChat();
“`

2.3 生成文本向量 (`/api/embeddings`)

“`javascript
async function generateEmbeddings() {
const text1 = “机器学习正在改变世界。”;
const text2 = “人工智能是未来的趋势。”;
const text3 = “如何种植有机蔬菜？”;

const embeddingModel = ‘nomic-embed-text’; // 确保你已下载此模型

console.log(\n--- 生成 Embeddings ---);
try {
const response1 = await ollama.embeddings({ model: embeddingModel, prompt: text1 });
const response2 = await ollama.embeddings({ model: embeddingModel, prompt: text2 });
const response3 = await ollama.embeddings({ model: embeddingModel, prompt: text3 });

const embedding1 = response1.embedding;
const embedding2 = response2.embedding;
const embedding3 = response3.embedding;

console.log(`'${text1.substring(0, 10)}...' Embedding 长度: ${embedding1.length}`);
console.log(`'${text2.substring(0, 10)}...' Embedding 长度: ${embedding2.length}`);
console.log(`'${text3.substring(0, 10)}...' Embedding 长度: ${embedding3.length}`);

// （可选）计算向量相似度
function cosineSimilarity(vec1, vec2) {
    const dotProduct = vec1.reduce((sum, val, i) => sum + val * vec2[i], 0);
    const magnitude1 = Math.sqrt(vec1.reduce((sum, val) => sum + val * val, 0));
    const magnitude2 = Math.sqrt(vec2.reduce((sum, val) => sum + val * val, 0));
    if (magnitude1 === 0 || magnitude2 === 0) return 0;
    return dotProduct / (magnitude1 * magnitude2);
}

const similarity12 = cosineSimilarity(embedding1, embedding2);
const similarity13 = cosineSimilarity(embedding1, embedding3);

console.log(`'${text1.substring(0, 10)}...' 和 '${text2.substring(0, 10)}...' 的余弦相似度: ${similarity12.toFixed(4)}`);
console.log(`'${text1.substring(0, 10)}...' 和 '${text3.substring(0, 10)}...' 的余弦相似度: ${similarity13.toFixed(4)}`);

} catch (error) {
console.error(“API Error:”, error);
console.error(Hint: Make sure you have downloaded an embedding model like '${embeddingModel}' using 'ollama pull ${embeddingModel}'.);
}
}

generateEmbeddings();
“`

2.4 列出本地模型 (`/api/tags`)

``javascript async function listModels() { console.log("\n--- 本地模型列表 ---"); try { const response = await ollama.list(); console.log("已下载模型:"); response.models.forEach(model => { console.log(– ${model.name} (大小: ${(model.size / (1024 * 1024)).toFixed(2)} MB, 修改时间: ${model.modified_at})`);
});
} catch (error) {
console.error(“API Error:”, error);
}
}

listModels();
“`

3. 使用 Curl 命令

对于简单的测试或脚本，你可以直接使用 curl 命令与 Ollama API 交互。这有助于理解底层的 HTTP 请求结构。

非流式文本生成:

bash curl http://localhost:11434/api/generate -d '{ "model": "llama2", "prompt": "讲一个关于猫的简短故事。", "stream": false }'

流式文本生成:

bash curl http://localhost:11434/api/generate -d '{ "model": "llama2", "prompt": "详细描述太阳系的八大行星。", "stream": true }'

非流式多轮对话:

bash curl http://localhost:11434/api/chat -d '{ "model": "llama2", "messages": [ {"role": "system", "content": "你是一个擅长给出旅行建议的AI。"}, {"role": "user", "content": "如果我想去海边度假，有什么推荐的地方？"} ], "stream": false }'

生成 Embeddings:

“`bash

需要安装一个 Embedding 模型，例如 nomic-embed-text

curl http://localhost:11434/api/embeddings -d ‘{
“model”: “nomic-embed-text”,
“prompt”: “向量数据库在 RAG 中的作用是什么？”
}’
“`

列出本地模型:

bash curl http://localhost:11434/api/tags

请注意，使用 curl 处理流式响应或解析复杂的 JSON 结构（尤其是流式）会比较麻烦，因此对于应用程序开发，强烈建议使用官方或社区提供的客户端库。

理解 API 参数和响应

在使用 Ollama API 时，了解一些核心参数和响应结构非常重要。

请求参数示例 (`/api/generate` 和 `/api/chat`)

参数	类型	必需?	描述
`model`	string	是	要使用的模型名称，例如 `'llama2'`。
`prompt`	string	`generate` 必需	输入给模型的文本（仅用于 `generate`）。
`messages`	array of dict	`chat` 必需	对话历史数组，每个字典包含 `'role'` (`'system'`, `'user'`, `'assistant'`) 和 `'content'` 字段（仅用于 `chat`）。
`stream`	boolean	否	是否以流式方式返回响应（默认为 `false`）。
`options`	dict	否	一个包含生成选项的字典，如 `temperature`, `top_p`, `num_predict`, `repeat_penalty`, `seed` 等。具体选项取决于模型和 Ollama 版本。
`system`	string	否	提供一个系统消息，用于指导模型的整体行为（仅用于 `generate`，在 `chat` 中应放在 `messages` 数组的开头）。
`template`	string	否	使用一个自定义模板来格式化 Prompt（仅用于 `generate`）。
`keep_alive`	string/int	否	控制模型在不使用后在内存中保留多长时间。可以是时间字符串 (如 “10m”, “1h”) 或秒数。设置为 `"-1"` 永不卸载，设置为 `"0"` 立即卸载（默认为 5分钟）。
`format`	string	否	指定响应的格式，例如 `'json'`。如果模型支持并理解 JSON 格式，这可以用于让模型输出结构化的 JSON 响应。

响应结构示例

`/api/generate` (非流式)

成功响应是一个 JSON 对象，包含：

json { "model": "llama2", "created_at": "2023-10-26T10:28:31.300724212Z", "response": "生成的文本内容...", "done": true, "context": [128001, 128009, ...], // 用于下一轮对话的可选上下文 "total_duration": 1234567, // 总耗时 (纳秒) "load_duration": 123456, // 模型加载耗时 (纳秒) "prompt_eval_count": 50, // Prompt 中的 token 数 "prompt_eval_duration": 12345, // Prompt 评估耗时 (纳秒) "eval_count": 100, // 生成的 token 数 "eval_duration": 234567 // 生成耗时 (纳秒) }

`/api/generate` (流式)

响应是一系列 JSON 对象，每个对象通过换行符分隔。最后一个对象包含 done: true。

json {"model":"llama2","created_at":"2023-10-26T10:30:00.123456Z","response":"生成文本的","done":false} {"model":"llama2","created_at":"2023-10-26T10:30:00.234567Z","response":"第一部分...","done":false} ... {"model":"llama2","created_at":"2023-10-26T10:30:05.987654Z","response":"最后部分。","done":false} {"model":"llama2","created_at":"2023-10-26T10:30:06.789012Z","done":true,"total_duration":...,"load_duration":...,"prompt_eval_count":...,"prompt_eval_duration":...,"eval_count":...,"eval_duration":...}

`/api/chat` (非流式)

成功响应是一个 JSON 对象，包含：

json { "model": "llama2", "created_at": "2023-10-26T10:35:01.987654321Z", "message": { "role": "assistant", "content": "助手的回复内容..." }, "done": true, "total_duration": ..., ... // 其他性能指标，同 generate }

`/api/chat` (流式)

响应是一系列 JSON 对象，每个对象通过换行符分隔。最后一个对象包含 done: true。与流式 generate 不同，中间的 JSON 对象包含一个 message 字段。

json {"model":"llama2","created_at":"2023-10-26T10:40:00.111222Z","message":{"role":"assistant","content":"助手的回复第一部分..."},"done":false} {"model":"llama2","created_at":"2023-10-26T10:40:00.333444Z","message":{"role":"assistant","content":"第二部分..."},"done":false} ... {"model":"llama2","created_at":"2023-10-26T10:40:05.555666Z","done":true,"total_duration":..., ...}

`/api/embeddings`

成功响应是一个 JSON 对象，包含：

json { "embedding": [0.123, -0.456, 0.789, ...], // 文本的向量表示数组 "total_duration": ..., ... // 其他性能指标 }

`/api/tags`

成功响应是一个 JSON 对象，包含：

json { "models": [ { "name": "llama2:latest", "modified_at": "2023-10-25T12:00:00.000000000Z", "size": 3826951666, "digest": "sha256:..." }, { "name": "mistral:latest", "modified_at": "2023-10-26T08:30:00.000000000Z", "size": 4100123456, "digest": "sha256:..." } // ... 其他模型 ] }

错误处理

在使用 API 时，可能会遇到各种错误，例如：

网络错误: 无法连接到 localhost:11434，可能是 Ollama 服务未运行或防火墙问题。
HTTP 错误状态码:
- 400 Bad Request: 请求体格式错误或缺少必需参数。
- 404 Not Found: 请求的端点不存在，或者请求的模型不存在（例如 ollama pull 未下载）。
- 500 Internal Server Error: Ollama 服务内部发生错误。
- 其他状态码。
Ollama 返回的错误信息: 有些错误会在 JSON 响应体中给出详细信息，即使 HTTP 状态码是 200 系列（流式响应中尤其如此）。

建议在代码中使用 try...except (Python) 或 try...catch (JavaScript) 块来捕获异常，并检查 API 响应的状态码和错误消息。

进阶使用和注意事项

自定义模型 (Modelfile): Ollama 允许你通过 Modelfile 定制模型行为，例如设置系统 Prompt、修改参数默认值、甚至组合多个模型层。你可以使用 /api/create 端点通过 API 创建自定义模型。
性能优化: 对于对延迟敏感的应用，考虑模型的 keep_alive 参数，避免频繁加载/卸载模型。选择更小、更快的模型也是一种优化方式。
资源监控: 在本地运行 LLMs 非常消耗 CPU、内存和 GPU 资源。监控系统资源使用情况，确保你的硬件能够承受负载。
异步操作: 对于流式或耗时操作（如模型下载），在应用程序中应使用异步编程（如 Python 的 asyncio 或 JavaScript 的 async/await）来避免阻塞主线程。Python 客户端库和 JavaScript 客户端库都提供了异步接口。
生产部署: 默认的 localhost 绑定仅适用于本地开发和测试。在生产环境中，需要配置 Ollama 绑定到特定的 IP 地址或域名，并考虑安全措施（如防火墙、认证等）。参考 Ollama 文档关于生产部署的指南。
API 兼容性: Ollama API 可能会随着版本更新而有所变化，尤其是预览或较新的功能。查阅 Ollama 官方文档或 GitHub 仓库获取最新信息和 API 参考。

总结

Ollama API 为开发者提供了将本地 LLMs 集成到各种应用程序的强大能力。通过 generate、chat 和 embeddings 等核心端点，你可以轻松实现文本生成、对话交互和语义表示功能。无论是使用 Python 或 JavaScript 客户端库，还是直接通过 HTTP 请求，与 Ollama API 交互都相对直观。

通过本文的快速入门指南，你应该已经掌握了连接 Ollama API、发送请求、处理响应以及执行基本任务的方法。现在，你可以开始尝试将 Ollama 集成到你的项目中，构建更智能、更注重隐私的本地 AI 应用了。不要犹豫深入探索 Ollama 的官方文档，了解更多高级功能和选项，充分发挥本地大模型的潜力！

Ollama API 快速入门指南：解锁本地大模型的编程能力

引言

为什么使用 Ollama API？

前置条件

Ollama API 概览

快速开始：使用 API

1. 使用 Python 客户端库 (ollama-python)

创建一个 Ollama 客户端实例

默认连接到 http://localhost:11434

如果 Ollama 服务不在默认地址/端口，可以这样指定：

client = ollama.Client(host=’http://YOUR_OLLAMA_HOST:PORT’)

1.1 文本生成 (/api/generate)

非流式生成

流式生成

使用 options 和 system 消息

1.2 多轮对话 (/api/chat)

多轮对话示例

流式聊天示例

1.3 生成文本向量 (/api/embeddings)

生成 Embeddings

注意：需要一个支持生成 embeddings 的模型。

例如，可以拉取 nomic-embed-text: ollama pull nomic-embed-text

1.4 列出本地模型 (/api/tags)

列出本地模型

1.5 其他模型管理操作

示例：拉取一个模型 (非阻塞，可以在后台运行 Ollama 命令或者使用 pull_stream 方法)

注意：这通常是一个耗时操作，建议在应用启动时或单独处理。

以下代码仅作演示，实际应用中需考虑用户界面反馈和错误处理。

try:

print(“\n— 尝试拉取新的模型 (非阻塞) —“)

# 这只是发起请求，下载在后台进行

pull_response = client.pull(model=’mistral’, stream=False)

print(f”拉取请求已发送: {pull_response}”)

except ollama.ResponseError as e:

print(f”\nAPI Error: {e}”)

except Exception as e:

print(f”\nAn error occurred: {e}”)

示例：删除一个模型

try:

print(“\n— 尝试删除模型 (假设存在一个名为 ‘test-model’ 的模型) —“)

# 谨慎操作，模型删除后无法恢复

# delete_response = client.delete(model=’test-model’)

# print(f”删除响应: {delete_response}”)

except ollama.ResponseError as e:

print(f”\nAPI Error: {e}”)

except Exception as e:

print(f”\nAn error occurred: {e}”)

示例：显示模型信息

2. 使用 JavaScript / Node.js 客户端库 (ollama)

或 yarn add ollama

2.1 文本生成 (/api/generate)

2.2 多轮对话 (/api/chat)

2.3 生成文本向量 (/api/embeddings)

2.4 列出本地模型 (/api/tags)

3. 使用 Curl 命令

需要安装一个 Embedding 模型，例如 nomic-embed-text

理解 API 参数和响应

请求参数示例 (/api/generate 和 /api/chat)

响应结构示例

/api/generate (非流式)

/api/generate (流式)

/api/chat (非流式)

/api/chat (流式)

/api/embeddings

/api/tags

错误处理

进阶使用和注意事项

总结

发表评论 取消回复

1. 使用 Python 客户端库 (`ollama-python`)

1.1 文本生成 (`/api/generate`)

1.2 多轮对话 (`/api/chat`)

1.3 生成文本向量 (`/api/embeddings`)

例如，可以拉取 nomic-embed-text: `ollama pull nomic-embed-text`

1.4 列出本地模型 (`/api/tags`)

2. 使用 JavaScript / Node.js 客户端库 (`ollama`)

2.1 文本生成 (`/api/generate`)

2.2 多轮对话 (`/api/chat`)

2.3 生成文本向量 (`/api/embeddings`)

2.4 列出本地模型 (`/api/tags`)

请求参数示例 (`/api/generate` 和 `/api/chat`)

`/api/generate` (非流式)

`/api/generate` (流式)

`/api/chat` (非流式)

`/api/chat` (流式)

`/api/embeddings`

`/api/tags`

发表评论取消回复