【笔记】动手学Ollama 第四章 Ollama REST API

最新推荐文章于 2025-10-21 10:13:45 发布

原创最新推荐文章于 2025-10-21 10:13:45 发布 · 1k 阅读

CC 4.0 BY-SA版权

文章标签：

正文详见：4.1 Ollama API 使用指南https://datawhalechina.github.io/handy-ollama/#/C4/1.%20Ollama%20API%20%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97

一、Ollama API 使用指南

通过 Ollama API，用户可以发送请求并接收模型生成的响应。

1、回答补全

POST /api/generate

使用指定的模型生成给定提示的响应。这是一个流式端点，因此会有一系列响应。

参数：

model：模型名称（必选）
prompt：生成响应的提示（必选）
images：图片消息，base64格式，用于多模态模型
format：模型返回的格式，目前只有json
stream：是否为流式输出
system：系统消息
context：先前返回的的上下文，可用保持简短的对话记忆
suffix：模型响应后的文本
raw：是否进行格式化
keep_alive：模型在内存中保持加载时间，默认为5m

curl http://localhost:11434/api/generate -d "{\"model\": \"llama3.1\", \"prompt\": \"为什么草是绿的\"}"

目前返回的是json对象流，包括model，created_at，respose，done。

我们将stream设置为false，则可以一次收到所有回复。

curl http://localhost:11434/api/generate -d "{\"model\": \"llama3.1\", \"prompt\": \"为什么草是绿的\",\"stream\":false}"

将format设置为json时，我们将得到JSON格式的输出。前提是我们在prompt中要指示模型以JSON格式相应。

curl http://localhost:11434/api/generate -d "{\"model\": \"llama3.1\", \"prompt\": \"为什么草是绿的\",\"stream\":false,\"format\":\"json\"}"

将seed设置为一个固定数值，得到可复现的输出：

图片输入（使用llava或bakllava），可以直接在ollama界面下载。图片格式为base64编码的images列表。

curl http://localhost:11434/api/generate -d '{
  "model": "llava",
  "prompt":"描述这张图片",
  "stream": false,
  "images": ["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"
  ]
}'

这个用windows的cmd操作起来太麻烦了，跳过。

2、对话补全

POST /api/chat

生成聊天中的下一条消息。这也是一个流式端点，因此会有一系列响应。

参数：

model：模型名称（必选）
message：聊天消息，用于保持聊天记忆
- role：消息角色，可以是systes、user、assistant、tool其中的一种
- content：消息内容
- images：图片消息，base64格式，用于多模态模型
- tool_calls：模型需使用的工具
tools：模型支持使用的工具。使用时需要将stream设置为false
options：其他模型参数，如temperature、seed等
keep_alive：模型在内存中保持加载时间，默认为5m

示例：

curl http://localhost:11434/api/chat -d "{\"model\": \"llama3.1\", \"messages\": [{\"role\": \"user\", \"content\": \"为什么草是绿的？\"}], \"stream\": false}"

通过messages携带历史对话记录：

curl http://localhost:11434/api/chat -d "{\"model\": \"llama3.1\", \"messages\": [{\"role\": \"user\", \"content\": \"为什么草是绿色的？\"}, {\"role\": \"assistant\", \"content\": \"因为草里面含有叶绿素。\"}, {\"role\": \"user\", \"content\": \"为什么叶绿素让草看起来是绿色的？\"}], \"stream\": false}"

3、创建模型

POST /api/create

参数：

model：要创建的模型名称
modefile：Modefile的内容
stream：是否流式输出
path：Modefile的路径

示例：

curl http://localhost:11434/api/create -d "{\"name\": \"mario\", \"modelfile\": \"FROM llama3\\nSYSTEM You are mario from Super Mario Bros.\"}"

4、复制模型

POST /api/copy

使用另一个名称复制已有模型。

curl http://localhost:11434/api/copy -d "{\"source\": \"llama3.1\", \"destination\": \"llama3-backup\"}"

5、删除模型

DELETE /api/delete

删除模型及其数据。

curl -X DELETE http://localhost:11434/api/delete -d "{\"name\": \"llama3.1\"}"

6、列出运行模型

GET /api/ps

列出当前加载到内存中的模型。

curl http://localhost:11434/api/ps

7、列出本地模型

GET /api/tags

列出本地可用的模型。

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

8、显示模型信息

POST /api/show

显示有关模型的信息，包括详细信息、modelfile、模板、参数、许可证、系统提示。

参数：

name：模型名称
verbose：是否返回详细相信息

curl http://localhost:11434/api/show -d "{\"name\": \"llama3.1\"}"

9、拉取模型

POST /api/pull

从 ollama 库下载模型。有一个很方便的点，中断的拉取操作会从断点继续下载，多个调用将共享相同的下载进度。

参数：

name：模型名称
insecure：是否允许对库进行不安全链接
stream：是否为流式输出

curl http://localhost:11434/api/pull -d "{\"name\": \"llama3.1\"}"

开始

拉取过程

结束

拉取好的模型

10、推送模型

POST /api/push

将模型上传到模型库。需要先注册 ollama.ai 并添加公钥。

首先，前往官网查看你的公钥保存地址Ollama keys · Settingshttps://ollama.com/settings/keys

前往响应文件找到自己的公钥

返回官方，点击Add Ollama Public Key，将公钥复制粘贴进去。这样就设置好了公钥

参数：

示例：

name：要推送的模型，格式为<namespace>/<model>:<tag>
insecure：是否对库进行不安全连接
stream：是否为流式输出

curl http://localhost:11434/api/push -d '{
  "name": "mattw/pygmalion:latest"
}'

不能直接覆盖或推送官方同名模型，你只能推送自己命名的模型。

首先将模型复制到你的用户名目录下

然后再进行推送

推送成功

11、生成嵌入

POST /api/embed

从模型生成嵌入。

参数：

model：模型名称
input：要生成嵌入的文本或文本列表
truncate：默认为true，超过上下文长度直接截断
options：其他模型参数
keep_alive：模型在内存中加载时间

示例：

curl http://localhost:11434/api/embed -d "{\"model\": \"llama3.1\", \"input\": \"为什么草是绿的？\"}"

多个输入

curl http://localhost:11434/api/embed -d "{\"model\": \"llama3.1\", \"input\": [\"为什么草是绿的？\", \"为什么天是蓝的？\"]}"

二、在Python中使用Ollama API

1、安装ollama库

pip install ollama

2、使用方法

from ollama import chat
from ollama import ChatResponse

response: ChatResponse = chat(model='llama3.1', messages=[
  {
    'role': 'user',
    'content': '为什么天空是蓝色的？',
  },
])
print(response['message']['content'])

print(response.message.content)

2、流式响应

将stream设置为true。

from ollama import chat

stream = chat(
    model='llama3.1',
    messages=[{'role': 'user', 'content': '为什么天空是蓝色的？'}],
    stream=True,
)

for chunk in stream:
  print(chunk['message']['content'], end='', flush=True)

你可以看到，运行过程中，输出是一点点输出的。并不是直接全部输出。

3、结构化输出

以 JSON 、 YAML 、 XML 或其他格式返回数据，使其更容易被机器解析和使用。更适合 API 、自动化工作流和数据存储。

{
  "description": "这是一只黑色的小猫",
  "activity": "正在草地上玩耍"
}

优势：

可以轻松提取特定字段，如直接提取“description”或“activity”
可控性高，可以精确控制模型的输出
结构化的数据更有利于存储、查询和分析

4、API调用

Ollama Python 库提供了丰富的接口，简化了与 Ollama 的交互。

① 聊天

ollama.chat(model='llama3.1', messages=[{'role': 'user', 'content': '为什么天空是蓝色的？'}])

② 生成

ollama.generate(model='llama3.1', prompt='为什么天空是蓝色的？')

③ 本地模型列表

ollama.list()

④ 显示模型信息

ollama.show('llama3.1')

⑤ 创建模型

ollama.create(model='example', from_="deepseek-r1:1.5b", system = "你是超级马里奥兄弟中的马里奥")

⑥ 复制模型

ollama.copy('llama3.1', 'user/llama3.1')

⑦ 删除模型

ollama.delete('llama3.1')

⑧ 拉取模型

ollama.pull('llama3.1')

⑨ 推送模型

ollama.push('user/llama3.1')

⑩ 生成嵌入

ollama.embeddings(model='llama3.1', prompt='天空是蓝色的因为瑞利散射')

# 批量生成embedding
ollama.embed(model='llama3.1', input=['天空是蓝色的', '草是绿色的'])

①① 进程

ollama.ps()

5、自定义客户端

通过Ollama实例化Client或AsynClint来创建自定义客户端。

参数：

host：要连接的Ollama主机
timeout：请求超时时间

同步客户端（Client）

同步客户端（Client）在你调用client.chat()方法时，会等待该请求完成并返回结果后才继续执行后续代码。

from ollama import Client
client = Client(
  host='http://localhost:11434',
  headers={'x-some-header': 'some-value'}
)
response = client.chat(model='llama3.1', messages=[
  {
    'role': 'user',
    'content': '为什么天空是蓝色的？',
  },
])
print(response)

异步客户端（AsyncClient）

异步客户端（AsyncClient）则是定义了一个异步函数chat()。通过await关键字，可以暂停该函数的执行知道AsyncClient().chat()的请求完成。

在此期间，其他的操作不会被阻塞。这对于高效率处理I/O操作或者希望同时执行多个任务的应用来说十分有用。

使用asyncio.run(chat())运行异步函数

import asyncio
from ollama import AsyncClient
import nest_asyncio

nest_asyncio.apply()

async def chat():
    message = {'role': 'user', 'content': '为什么天空是蓝色的？'}
    response = await AsyncClient().chat(model='llama3.1', messages=[message])
    print(response)

asyncio.run(chat())

设置 stream=True 修改函数以返回 Python 异步生成器：

import asyncio
from ollama import AsyncClient
import nest_asyncio

nest_asyncio.apply()
async def chat():
  message = {'role': 'user', 'content': '为什么天空是蓝色的？'}
  async for part in await AsyncClient().chat(model='llama3.1', messages=[message], stream=True):
    print(part['message']['content'], end='', flush=True)

asyncio.run(chat())