Python 中的 Ollama API，然後是託管端點

設定 Python 客戶端

首先安裝 Ollama 本身，啟動它，並從終端機拉取一個模型：ollama pull llama3。伺服器監聽在 http://localhost:11434。然後在虛擬環境中安裝 Python 套件：

Copypython -m venv .venv
source .venv/bin/activate
pip install ollama openai

ollama 套件會與 Ollama 的 /api 原生路由進行通訊。openai 套件則用於本教程的第二部分，其目標為託管端點。如果你在編寫程式碼前偏好使用視覺化工具，請參閱 使用 Ollama 與圖形使用者介面 的說明。

在終端機中執行 ollama list 來檢查安裝。如果你的模型出現在那裡，Python 就會找到它。如果稍後出現連線錯誤，伺服器可能沒有運行。

你的第一個對話請求

以下是 ollama API Python 基礎的一次性程式碼片段：包含系統訊息、使用者訊息以及兩個選項。

Copyimport ollama

resp = ollama.chat(
    model="llama3",
    messages=[
        {"role": "system", "content": "Answer in one short paragraph."},
        {"role": "user", "content": "What is a context window?"},
    ],
    options={"temperature": 0.4, "num_ctx": 8192},
)
print(resp["message"]["content"])

回覆是一個類似字典的物件；文字位於 message.content 中。在 options 中你可以設定生成參數。temperature 控制隨機性，num_ctx 設定該次呼叫的上下文長度。除非你提高它，否則 Ollama 預設為相當小的上下文，這會讓貼上長文件的人感到驚訝，因為他們得到的答案會忽略開頭。

對於多輪聊天，保持一個訊息列表並自行附加每個回覆。Ollama 與大多數聊天 API 一樣，在呼叫之間是無狀態的。

串流回應

沒有串流輸出時，你需要等待完整的答案。使用 stream=True 時，函式會返回一個生成器，你可以隨著資料到達列印片段：

Copyimport ollama

for part in ollama.chat(
    model="llama3",
    messages=[{"role": "user", "content": "Explain recursion with a cooking analogy."}],
    stream=True,
):
    print(part["message"]["content"], end="", flush=True)

每個部分都包含一個小的 message.content。最後一個部分的 done 設為 true，並包含計時與 token 計數。對於網頁應用程式，請透過伺服器發送事件或 websocket 將這些片段轉發至瀏覽器。

你實際會遇到的錯誤

兩種故障涵蓋了大多數初學者的問題。

Copyimport ollama

try:
    ollama.chat(model="llama3", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as exc:
    if exc.status_code == 404:
        print("Model missing. Run: ollama pull llama3")
    else:
        raise
except ConnectionError:
    print("Cannot reach Ollama. Is the server running on port 11434?")

來自 ResponseError 的 404 表示模型名稱與你拉取的模型不符。名稱包含標籤，因此 llama3 和 llama3:70b 是不同的模型。連線錯誤表示伺服器未啟動，或者你處於容器內，其中 localhost 指向容器而非主機。在這種情況下，請傳遞具有正確主機的客戶端：ollama.Client(host="http://host.docker.internal:11434")。

更多模式收錄於 常見 Ollama API 錯誤。

相同的程式碼，託管端點

本地模型受你的記憶體和速度限制。當腳本必須在伺服器上運行、處理許多並行作業或使用更大的上下文視窗時，託管端點更容易。訣竅是針對 OpenAI SDK 編寫程式，並將 base URL、金鑰和模型視為配置：

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.ollamansfw.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt, history=None):
    messages = (history or []) + [{"role": "user", "content": prompt}]
    out = ""
    for chunk in client.chat.completions.create(model=MODEL, messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            piece = chunk.choices[0].delta.content
            out += piece
            print(piece, end="", flush=True)
    return out

ask("Explain recursion with a cooking analogy.")

對於本地 Ollama，設定 LLM_BASE_URL=http://localhost:11434/v1，LLM_API_KEY=ollama（任何非空字串在那裡都會被接受）和 LLM_MODEL=llama3。對於託管 API，使用上述預設值、你的真實金鑰和模型 uncensored。程式碼中的其他內容不會改變。

在 API 金鑰頁面 取得金鑰。新帳戶可以一鍵領取 $0.50 試用額度，無需付款，有效期為 7 天。該模型來自獨立供應商的開放權重模型，經過調整以在法律允許的成人使用中無內容拒絕地回答。它僅限文字，並非任何大型實驗室的官方 API。

並行執行許多提示詞

一台機器上的本地模型通常一次處理一個請求，所以迴圈是串行的。託管端點允許並行請求，這使批次工作快得多。將工作程序數量保持在你的金鑰限制之下：完整金鑰為 8 個並行請求，試用金鑰為 2 個。

Copyfrom concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

def summarize(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarize in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

docs = ["first text", "second text", "third text"]
with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(summarize, docs))
print(results)

六個工作程序在 8 的限制之下留有餘地。如果工作程序收到 429，OpenAI SDK 預設會重試幾次，但請為長時間運行添加你自己的退避機制。還要記住，每個串流請求都會佔用其槽位直到串流結束，所以不要在相同的試用金鑰上混合長時間的串流聊天和大型批次。

需要規劃的差異

• 沒有僅限本地的選項。 num_ctx 和 keep_alive 在託管端沒有意義。上下文視窗為 100,000 token，包含提示詞和完成內容。
• 速率限制。 完整金鑰允許 8 個並行請求和每分鐘 300 個請求；試用金鑰允許 2 個和 60 個。超過此限制你會收到 429 並帶有 rate_limited 或 concurrency。暫停後重試；在臨時超載時，回應會帶有 Retry-After: 5。
• 成本。 輸入為每 1M token $0.15，輸出為每 1M token $0.50。發送 2,000 個提示詞的腳本，每個提示詞包含 600 個輸入 token 和 400 個輸出 token，花費 2,000 x (600 x $0.15 + 400 x $0.50) / 1M = 2,000 x $0.00029 = $0.58。
• 計費。 預付額度，從 $20 到 $500，使用加密貨幣支付（TRC20 上的 USDT 或 Base 上的 USDC）。失敗或被拒絕的請求不會收費。

若要並排查看端點，請閱讀 我們的 API 定價說明 或 文件。

更多指南

• Ollama API 與 OpenAI API：端點和程式碼
• 如何使用 Ollama 搭配圖形介面（以及託管備援）