当前位置：首页 > news >正文

Ollama API 应用指南

news 2025/8/12 5:02:11

在这里插入图片描述

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维