Ollama API 应用指南

news2025/4/24 12:53:26

在这里插入图片描述

1. 基础信息

默认地址: http://localhost:11434/api
数据格式: application/json
支持方法: POST（主要）、GET（部分接口）

2. 模型管理 API

(1) 列出本地模型

端点: GET /api/tags
功能: 获取已下载的模型列表。

示例:

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

import requests
response = requests.get("http://localhost:11434/api/tags")
print(response.json()["models"])

(2) 拉取模型

端点: POST /api/pull
参数:
- name: 模型名称（必需，如 llama3:8b）
- stream: 是否流式显示进度（默认 true）
- insecure: 是否跳过 TLS 验证（默认 false）

示例:

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

response = requests.post(
    "http://localhost:11434/api/pull",
    json={"name": "mistral", "stream": False}
)

(3) 删除模型

端点: DELETE /api/delete
参数: name（模型名称）

示例:

curl -X DELETE http://localhost:11434/api/delete -d '{"name": "llama2"}'

response = requests.delete(
    "http://localhost:11434/api/delete",
    json={"name": "llama2"}
)

(4) 创建自定义模型

端点: POST /api/create
参数: name（模型名）、modelfile（模型配置内容）

示例:

curl http://localhost:11434/api/create -d '{
  "name": "my-llama",
  "modelfile": "FROM llama3\nSYSTEM 你是一个法律助手"
}'

3. 文本生成与交互

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

参数:

{
  "model": "模型名",
  "prompt": "输入文本",
  "system": "系统提示（可选）",
  "template": "模板（覆盖默认提示格式）",
  "context": [数组，历史上下文ID],
  "stream": false,
  "options": {
    "temperature": 0.8,
    "top_p": 0.9,
    "max_tokens": 1000,
    "num_ctx": 4096
  }
}

响应:

{
  "model": "模型名",
  "response": "生成文本",
  "context": [新的上下文ID],
  "done": true
}

Python 流式处理:

response = requests.post(
    "http://localhost:11434/api/generate",
    json={"model": "llama3", "prompt": "写一篇科幻小说开头", "stream": True},
    stream=True
)
for line in response.iter_lines():
    if line:
        print(json.loads(line)["response"], end="", flush=True)

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

参数:

{
  "model": "模型名",
  "messages": [
    {"role": "user", "content": "内容1"},
    {"role": "assistant", "content": "内容2"}
  ],
  "stream": false
}

响应:

{
  "message": {"role": "assistant", "content": "回复内容"},
  "context": [上下文ID]
}

Python 示例:

messages = [
    {"role": "user", "content": "如何学习Python？"},
    {"role": "assistant", "content": "先掌握基础语法。"},
    {"role": "user", "content": "推荐一本书？"}
]
response = requests.post(
    "http://localhost:11434/api/chat",
    json={"model": "llama3", "messages": messages}
)
print(response.json()["message"]["content"])

4. 嵌入向量 (`/api/embeddings`)

参数:

{
  "model": "模型名",
  "prompt": "输入文本",
  "options": {"temperature": 0.5}  # 可选参数
}

响应:

{
  "embedding": [0.1, -0.2, ...]  # 浮点数数组
}

Python 示例:

response = requests.post(
    "http://localhost:11434/api/embeddings",
    json={"model": "llama3", "prompt": "自然语言处理"}
)
vector = response.json()["embedding"]

5. 高级功能与参数

(1) 上下文延续

在生成请求中传递 context 数组以维持对话状态：

response1 = requests.post("/api/generate", json={"model": "llama3", "prompt": "你好"})
context = response1.json()["context"]

response2 = requests.post(
    "/api/generate",
    json={"model": "llama3", "prompt": "继续上文", "context": context}
)

(2) 性能调优参数

options 字段支持以下关键参数：

{
  "num_ctx": 4096,      // 上下文窗口大小
  "num_gqa": 8,         // Grouped-Query Attention 组数
  "num_gpu": 1,         // GPU 层数（仅限支持GPU的模型）
  "main_gpu": 0,        // 主 GPU 索引
  "temperature": 0.7,   // 随机性（0-1）
  "repeat_penalty": 1.1 // 抑制重复生成
}

6. 错误处理

常见状态码:
- 400: 请求参数错误
- 404: 模型不存在
- 500: 服务器内部错误
错误响应格式:
```
{
  "error": "错误描述"
}
```

7. 完整 Python 客户端示例

import ollama

# 生成文本
response = ollama.generate(
    model='llama3', 
    prompt='用一句话解释人工智能',
    options={'temperature': 0.5}
)
print(response['response'])

# 流式对话
stream = ollama.chat(
    model='llama3',
    messages=[{'role': 'user', 'content': '写一首五言绝句'}],
    stream=True
)
for chunk in stream:
    print(chunk['message']['content'], end='', flush=True)

# 获取嵌入向量
embedding = ollama.embeddings(model='llama3', prompt='深度学习')
print(embedding['embedding'][:5])  # 打印前5维