Ollama REST API 入门教程：接口详解与示例

前提条件

确保已经安装并启动了Ollama服务。可以参考该本地部署 DeepSeek-R1 大模型指南：基于 Ollama 的完整流程进行安装。默认情况下，Ollama服务监听在http://localhost:11434。

主要接口

• 生成文本：POST /api/generate，使用提供的模型生成给定提示的响应。
• 聊天对话：POST /api/chat，用于进行聊天对话，支持多轮对话和工具调用等功能。
• 模型管理：包括POST /api/pull（拉取模型）、POST /api/delete（删除模型）。
• 模型列表：GET /api/tags，获取可用模型列表。
• 生成文本的嵌入向量 POST /api/embed 获取文本嵌入向量，嵌入向量是将文本转换为数值向量的一种表示形式

接口使用示例

生成文本

curl http://localhost:11434/api/generate -d '{
  "model": "llama2",
  "prompt": "What color is the sky at different times of the day? Respond using JSON",
  "format": "json",
  "stream": false
}'

上述命令中，使用llama2模型生成关于天空在一天不同时间颜色的JSON格式响应。

聊天对话

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:0.5b",
  "messages": [
    {"role": "system", "content": "你现在是一名合格的售票员，你还可以随意生成一些航班路线提供给用户，请扮演好您的角色。"},
    {"role": "user", "content": "你好，我想订一张机票。"},
    {"role": "assistant", "content": "好的，请问您要去哪里？"},
    {"role": "user", "content": "我要去北京。"},
    {"role": "user", "content": "有哪些航班可选？"}
  ],
  "stream": false
}'

此示例中，与qwen2.5:0.5b模型进行多轮聊天对话，模拟用户订机票的场景。

拉取模型

curl http://localhost:11434/api/pull -d '{
  "name": "phi3"
}'

该命令用于拉取名为phi3的模型到本地。

获取模型列表

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

执行此命令可以获取本地已有的模型列表。

生成文本的嵌入向量

在 Ollama 中，/api/embed 这个 REST API 主要用于生成文本的嵌入向量（embeddings）。下面为你详细介绍它的作用、使用场景以及使用示例。

作用

嵌入向量是将文本转换为数值向量的一种表示形式。这些向量能够捕捉文本的语义信息，使得在高维空间中，语义相近的文本对应的向量距离也更近。/api/embed API 接收一段文本作为输入，使用指定的模型将其转换为固定长度的向量。

使用场景

• 语义搜索：将搜索查询和文档库中的所有文档都转换为嵌入向量，通过计算向量之间的相似度（如余弦相似度），可以快速找到与查询语义最匹配的文档。
• 文本分类：利用文本的嵌入向量作为特征，训练机器学习模型进行文本分类任务，如情感分析、主题分类等。
• 聚类分析：根据文本的嵌入向量对文本进行聚类，将语义相近的文本归为一类，有助于发现文本数据中的潜在结构。

请求参数

调用 /api/embed API 时，通常需要在请求体中包含以下参数：

• model：要使用的模型名称，例如 llama2 。
• text：需要生成嵌入向量的文本内容。

使用示例

使用 curl 调用

curl http://localhost:11434/api/embed -d '{
    "model": "llama2",
    "text": "这是一段用于生成嵌入向量的示例文本。"
}'

Python 代码示例

import requests
import json

url = "http://localhost:11434/api/embed"
data = {
    "model": "llama2",
    "text": "这是一段用于生成嵌入向量的示例文本。"
}

response = requests.post(url, json=data)
if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"请求失败，状态码: {response.status_code}，错误信息: {response.text}")

响应结果

成功调用 /api/embed API 后，会返回一个 JSON 对象，其中包含生成的嵌入向量。示例响应如下：

{
    "embedding": [
        0.0123,
        -0.0456,
        0.0789,
        ...  // 更多向量元素
    ]
}

这个 embedding 字段的值就是输入文本对应的嵌入向量。不同的模型生成的向量长度可能不同。

总结

通过这些接口，你可以轻松地与Ollama模型进行交互，生成文本、聊天对话、拉取模型、获取模型列表等。欢迎关注：庄智曰

参考文献

ollama rest api