1. 基礎信息
- 默認地址:
http://localhost:11434/api - 數據格式:
application/json - 支持方法:
POST（主要）、GET（部分接口）
2. 模型管理 API
(1) 列出本地模型
- 端點:
GET /api/tags - 功能: 獲取已下載的模型列表。
- 示例:
curl http://localhost:11434/api/tagsimport 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. 注意事項
-
模型兼容性
- 不同模型支持的參數可能不同（如 GPU 加速需模型編譯時啟用 CUDA）。
-
長上下文處理
- 增大
num_ctx可能導致內存不足，建議逐步測試。
- 增大
-
流式傳輸優化
- 使用
stream=True時，客戶端需逐塊處理數據以減少延遲。
- 使用
-
自定義模型集成
- 通過
Modelfile創建的模型可直接通過 API 調用（model: 自定義模型名）。
- 通過
通過此指南，可全面掌握 Ollama API 的核心功能，適用于開發聊天機器人、自動化腳本、語義分析等多種場景。
 -part7)
