Ollama API 应用指南

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维

---

8. 注意事项

1. 模型兼容性

   • 不同模型支持的参数可能不同（如 GPU 加速需模型编译时启用 CUDA）。

2. 长上下文处理

   • 增大 num_ctx 可能导致内存不足，建议逐步测试。

3. 流式传输优化

   • 使用 stream=True 时，客户端需逐块处理数据以减少延迟。

4. 自定义模型集成

   • 通过 Modelfile 创建的模型可直接通过 API 调用（model: 自定义模型名）。

---

通过此指南，可全面掌握 Ollama API 的核心功能，适用于开发聊天机器人、自动化脚本、语义分析等多种场景。