Ollama Flow
一個強大且易用的 Python 函式庫,用於與 Ollama API 互動。
功能特色
- 🚀 簡潔易用的 API - 提供直觀的 Python 介面
- 🎯 結構化輸出 - 支援 JSON Schema 和 Pydantic 模型
- 🌊 串流模式 - 即時獲取生成內容
- 💬 完整聊天支援 - 支援多輪對話和工具調用
- 🔤 嵌入向量 - 生成文本嵌入向量
- ✅ 智能模型驗證 - 自動檢查模型是否存在,提供友好的錯誤提示
- 💾 緩存機制 - 智能緩存模型列表,提升性能
- 🛡️ 類型安全 - 完整的類型提示支援
- 📦 零依賴 - 僅依賴
requests和pydantic
支援的 API 端點
/api/generate- 生成完成/api/chat- 聊天完成/api/embed- 生成嵌入向量
安裝
pip install ollama-flow
或者從源碼安裝:
git clone https://github.com/your-username/ollama-flow.git
cd ollama-flow
pip install -e .
快速開始
基本使用
from ollama_flow import OllamaClient
# 建立客戶端
client = OllamaClient(base_url="http://localhost:11434")
# 生成文本
response = client.generate(
model="llama3.2",
prompt="解釋什麼是機器學習?",
stream=False
)
print(response.response)
聊天對話
from ollama_flow import OllamaClient, ChatMessage
client = OllamaClient()
messages = [
ChatMessage(role="system", content="你是一個有用的助手。"),
ChatMessage(role="user", content="你好!")
]
response = client.chat(
model="llama3.2",
messages=messages,
stream=False
)
print(response.message.content)
結構化輸出
from ollama_flow import OllamaClient
from pydantic import BaseModel, Field
from typing import List
class Product(BaseModel):
name: str = Field(..., description="產品名稱")
price: float = Field(..., description="價格")
features: List[str] = Field(..., description="功能特點")
client = OllamaClient()
# 使用 Pydantic 模型
response = client.generate_structured(
model="llama3.2",
prompt="創建一個智慧型手機產品資訊,請用 JSON 格式回應。",
schema=Product,
stream=False
)
# 解析結構化回應
product = client.parse_structured_response(response.response, Product)
print(f"產品名稱:{product.name}")
print(f"價格:${product.price}")
print(f"功能:{', '.join(product.features)}")
串流模式
from ollama_flow import OllamaClient
client = OllamaClient()
response_stream = client.generate(
model="llama3.2",
prompt="寫一篇關於人工智慧的文章。",
stream=True
)
print("生成中:", end="", flush=True)
for chunk in response_stream:
if chunk.get("done", False):
print("\n生成完成!")
break
else:
print(chunk.get("response", ""), end="", flush=True)
生成嵌入向量
from ollama_flow import OllamaClient
client = OllamaClient()
response = client.embed(
model="all-minilm",
input="這是要轉換為嵌入向量的文本。"
)
print(f"嵌入維度:{len(response.embeddings[0])}")
print(f"嵌入向量:{response.embeddings[0][:5]}...") # 顯示前5個值
進階功能
模型驗證
# 預設開啟模型驗證
client = OllamaClient(check_models=True)
# 獲取可用模型列表
models = client.list_models()
print(f"可用模型:{models}")
# 刷新模型緩存
models = client.refresh_models_cache()
# 關閉模型驗證(不推薦)
client_no_check = OllamaClient(check_models=False)
# 當使用不存在的模型時,會拋出 ValueError
try:
client.generate(model="nonexistent-model", prompt="Hello")
except ValueError as e:
print(f"模型驗證錯誤:{e}")
JSON 模式
# 使用 JSON 模式
response = client.generate_json(
model="llama3.2",
prompt="列出三個程式設計語言及其特點。請用 JSON 格式回應。",
stream=False
)
import json
data = json.loads(response.response)
print(json.dumps(data, indent=2, ensure_ascii=False))
自定義 JSON Schema
# 使用自定義 JSON Schema
person_schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"hobbies": {"type": "array", "items": {"type": "string"}}
},
"required": ["name", "age"]
}
response = client.generate_structured(
model="llama3.2",
prompt="創建一個虛構角色的資訊。",
schema=person_schema,
stream=False
)
上下文管理器
# 使用上下文管理器自動清理連線
with OllamaClient() as client:
response = client.generate(
model="llama3.2",
prompt="你好!",
stream=False
)
print(response.response)
API 參考
OllamaClient
主要的客戶端類別,提供與 Ollama API 的介面。
初始化
client = OllamaClient(
base_url="http://localhost:11434", # Ollama 服務器 URL
timeout=30, # 請求超時時間(秒)
check_models=True # 是否在調用前檢查模型是否存在
)
方法
generate()- 生成文本完成chat()- 聊天完成embed()- 生成嵌入向量generate_json()- 生成 JSON 格式回應generate_structured()- 生成結構化回應chat_json()- 聊天生成 JSON 格式回應chat_structured()- 聊天生成結構化回應parse_structured_response()- 解析結構化回應list_models()- 獲取可用模型列表refresh_models_cache()- 刷新模型緩存
資料模型
GenerateRequest
model: 模型名稱prompt: 提示文本format: 回應格式(可選)stream: 是否使用串流模式options: 模型參數(可選)
ChatMessage
role: 角色(system/user/assistant/tool)content: 訊息內容images: 圖像列表(可選)
ChatRequest
model: 模型名稱messages: 對話訊息列表format: 回應格式(可選)stream: 是否使用串流模式tools: 工具定義(可選)
EmbedRequest
model: 模型名稱input: 輸入文本或文本列表truncate: 是否截斷長文本
範例
查看 examples/ 目錄中的詳細範例:
basic_usage.py- 基本使用方法structured_output.py- 結構化輸出範例streaming.py- 串流模式範例model_validation.py- 模型驗證功能範例
錯誤處理
from ollama_flow import OllamaClient
client = OllamaClient()
try:
response = client.generate(
model="llama3.2",
prompt="你好!",
stream=False
)
print(response.response)
except Exception as e:
print(f"發生錯誤:{e}")
需求
- Python 3.7+
- requests >= 2.31.0
- pydantic >= 2.0.0
- 運行中的 Ollama 服務
許可證
MIT License
貢獻
歡迎提交 Issue 和 Pull Request!
- Fork 這個專案
- 建立您的功能分支 (
git checkout -b feature/amazing-feature) - 提交您的變更 (
git commit -m 'Add some amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 開啟一個 Pull Request
更新日誌
v0.1.0
- 初始發布
- 支援 generate, chat, embed API
- 結構化輸出支援
- 串流模式支援
- 智能模型驗證功能
- 模型列表緩存機制
- 完整的類型提示
相關連結
- Ollama - 本地 LLM 運行平台
- Ollama API 文檔
- Pydantic - 資料驗證函式庫
Metadata
Release files for ollama-flow 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ollama_flow-0.1.0.tar.gz | 50.4 kB | Without provenance | Details for ollama_flow-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ollama_flow-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ollama_flow-0.1.0-py3-none-any.whl |
Total release size: 59.9 kB
Release files / ollama_flow-0.1.0.tar.gz
| Download URL | ollama_flow-0.1.0.tar.gz |
|---|---|
| Size | 50.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
54c74d574e6ead1340c139a1ef9c7aa0d8a2405a68b69a60269295259412f066
|
|
BLAKE2b-256 checksum How to use checksums |
5ba10c41ff7e24c0bb3d10561e80220cd4ac97596db0608c1e9659136376e9e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.13
|
Release files / ollama_flow-0.1.0-py3-none-any.whl
| Download URL | ollama_flow-0.1.0-py3-none-any.whl |
|---|---|
| Size | 9.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
446e561218058ffbcc78ec9a6faff4e9a391d83ffe554c5ea7fe1652aaf0c1c4
|
|
BLAKE2b-256 checksum How to use checksums |
02fa8be60b37d87d5b6e6815958eef8b3c6f8d94e9711888c4de0120d511dde6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.11.13
|
Security for ollama-flow 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.