1. Ollama 简介

Ollama 是一个开源项目，旨在简化大型语言模型（LLM）在本地计算机上的运行和管理。它提供了一个命令行工具和一套 RESTful API，让开发者能够轻松地拉取、运行、管理和与各种开源模型（如 Llama、Mistral、CodeLlama 等）进行交互。

其核心优势在于：

• 开箱即用：通过简单的命令即可下载和运行模型。
• 跨平台：支持 macOS、Linux 和 Windows。
• 模型库丰富：内置了众多经过优化的热门开源模型。
• 提供 API：通过 HTTP API 暴露模型能力，方便集成到其他应用中。

2. Ollama API 概览

Ollama 在本地启动一个服务（默认端口为 11434），提供了一套 RESTful API。这套 API 是开发者将 Ollama 模型能力集成到自己应用程序中的主要方式。

主要 API 端点包括：

• /api/generate：用于生成文本补全（单轮对话）。
• /api/chat：用于多轮对话（Chat）。
• /api/embeddings：用于获取文本的向量嵌入。
• /api/tags：用于列出本地可用的模型。
• /api/pull：用于从 Ollama 库拉取模型。
• /api/ps：用于查看当前正在运行的模型。
• /api/copy：用于复制一个已有模型。
• /api/delete：用于删除本地模型。

3. 核心 API 接口详解

3.1 生成文本：/api/generate

这是最基础的接口，用于向模型发送一个提示（prompt）并获取生成的文本回复。

请求方法：POST

请求体示例：

{
  "model": "llama3.2",
  "prompt": "为什么天空是蓝色的？",
  "stream": false,
  "options": {
    "temperature": 0.7,
    "top_p": 0.9,
    "num_predict": 100
  }
}

参数说明：

• model（必需）：要使用的模型名称，如 llama3.2, mistral。
• prompt（必需）：输入的文本提示。
• stream：是否以流式（stream）方式返回结果，默认为 false。设为 true 时，响应为 Server-Sent Events (SSE) 格式。
• options：模型生成参数，用于控制生成行为。
  • temperature：控制随机性（0-1），值越高输出越随机。
  • top_p：核采样参数，控制候选词的范围。
  • num_predict：生成的最大 token 数量。

响应示例（stream: false）：

{
  "model": "llama3.2",
  "created_at": "2024-01-01T00:00:00.000000Z",
  "response": "天空呈现蓝色是由于瑞利散射...",
  "done": true,
  "context": [...],
  "total_duration": 503514000,
  "load_duration": 1000000,
  "prompt_eval_count": 15,
  "prompt_eval_duration": 38000000,
  "eval_count": 45,
  "eval_duration": 464514000
}

3.2 对话聊天：/api/chat

此接口专为多轮对话设计，可以维护对话历史上下文。

请求方法：POST

请求体示例：

{
  "model": "llama3.2",
  "messages": [
    {
      "role": "user",
      "content": "你好，请介绍下你自己。"
    },
    {
      "role": "assistant",
      "content": "你好！我是由 Meta 开发的 Llama 3.2 模型..."
    },
    {
      "role": "user",
      "content": "你能帮我写一段 Python 代码吗？"
    }
  ],
  "stream": false,
  "options": {
    "temperature": 0.8
  }
}

参数说明：

• messages（必需）：一个消息对象数组，每个对象包含 role（user, assistant, system）和 content。
• 其他参数与 /api/generate 类似。

响应示例：

{
  "model": "llama3.2",
  "created_at": "2024-01-01T00:00:00.000000Z",
  "message": {
    "role": "assistant",
    "content": "当然可以。以下是一个简单的 Python 脚本示例..."
  },
  "done": true,
  "total_duration": 1200000000,
  ...
}

3.3 获取嵌入向量：/api/embeddings

此接口用于将文本转换为高维向量（嵌入），常用于语义搜索、聚类等任务。

请求方法：POST

请求体示例：

{
  "model": "nomic-embed-text",
  "prompt": "机器学习是人工智能的一个分支。"
}

响应示例：

{
  "embedding": [0.123, -0.456, 0.789, ...]
}

3.4 模型管理接口

• GET /api/tags：列出本地已下载的模型。
• POST /api/pull：从 Ollama 库拉取（下载）一个模型。请求体需包含 {"name": "模型名"}。
• POST /api/delete：删除本地的一个模型。请求体需包含 {"name": "模型名"}。
• GET /api/ps：查看当前正在运行的模型实例。

4. 使用示例（Python）

以下是一个使用 Python 的 requests 库调用 Ollama API 的完整示例。

import requests
import json
Ollama 服务地址
OLLAMA_HOST = "http://localhost:11434"
1. 列出本地模型
def list_models():
response = requests.get(f"{OLLAMA_HOST}/api/tags")
if response.status_code == 200:
models = response.json().get("models", [])
for model in models:
print(f"模型: {model['name']}")
else:
print("请求失败:", response.status_code)
2. 生成文本（非流式）
def generate_text(prompt, model="llama3.2"):
url = f"{OLLAMA_HOST}/api/generate"
payload = {
"model": model,
"prompt": prompt,
"stream": False,
"options": {
"temperature": 0.7,
"num_predict": 150
}
}
response = requests.post(url, json=payload)
if response.status_code == 200:
result = response.json()
return result.get("response")
else:
print("生成失败:", response.status_code, response.text)
return None
3. 流式生成文本
def generate_text_stream(prompt, model="llama3.2"):
url = f"{OLLAMA_HOST}/api/generate"
payload = {
"model": model,
"prompt": prompt,
"stream": True
}
with requests.post(url, json=payload, stream=True) as response:
if response.status_code == 200:
for line in response.iter_lines():
if line:
decoded_line = line.decode('utf-8')
if decoded_line.startswith("data: "):
json_str = decoded_line[6:]
if json_str.strip() == "[DONE]":
break
try:
data = json.loads(json_str)
chunk = data.get("response", "")
if chunk:
print(chunk, end="", flush=True)
except json.JSONDecodeError:
pass
else:
print("流式请求失败:", response.status_code)
4. 对话聊天
def chat(messages, model="llama3.2"):
url = f"{OLLAMA_HOST}/api/chat"
payload = {
"model": model,
"messages": messages,
"stream": False
}
response = requests.post(url, json=payload)
if response.status_code == 200:
result = response.json()
return result.get("message", {}).get("content")
else:
print("对话失败:", response.status_code, response.text)
return None
if name == "main":
# 示例用法
print("=== 列出模型 ===")
list_models()
print("\n=== 生成文本 ===")
answer = generate_text("用一句话解释人工智能。")
print("回答:", answer)
print("\n=== 流式生成 ===")
generate_text_stream("讲一个简短的笑话。")
print("\n=== 对话 ===")
chat_history = [
{"role": "user", "content": "你好"},
{"role": "assistant", "content": "你好！有什么可以帮你的？"},
{"role": "user", "content": "Python 里怎么读取文件？"}
]
reply = chat(chat_history)
print("助手回复:", reply)

5. 常见问题与注意事项

• 服务未启动：确保已通过命令行 ollama serve 启动了 Ollama 服务。
• 模型未下载：首次使用某个模型前，需要通过 ollama pull <模型名> 或 API 拉取。
• 流式响应处理：当 stream=true 时，响应是 SSE 格式，需要逐行解析 data: 前缀的 JSON。
• 性能与硬件：模型运行需要足够的 RAM 和 VRAM。较大的模型（如 70B 参数）需要高性能显卡。
• 上下文长度：注意不同模型的上下文窗口（Context Window）限制，超长文本可能需要截断或分块处理。
• API 超时：生成长文本时，适当设置客户端的超时时间。

6. 总结

Ollama API 提供了一套简洁而强大的接口，让开发者能够轻松地在本地集成和调用各种大型语言模型。通过掌握 /api/generate、/api/chat、/api/embeddings 等核心端点，并结合模型管理接口，你可以快速构建基于本地 LLM 的智能应用。