Ollama API 教學：對話、串流、JSON 輸出到工具呼叫，附實際跑出來的回應

Ollama 裝好了，在終端機裡一問一答也試過了。下一步通常是：我要怎麼從自己的程式，或是 n8n 這類工具去叫它？

答案是它的 API。Ollama 開著的時候，本身就是一台伺服器，位置在 http://localhost:11434。

這篇把最常用的幾種呼叫走一遍。每一個請求我都實際送過，回應是原樣貼上來的。日期是 2026 年 10 月 13 日，Ollama 是 0.40.3，模型用 qwen3:4b-instruct，機器是一台沒有顯卡的 Linux 測試機，所以文中的秒數都偏慢。

還沒裝的話，先看Ollama 教學。

先確認它有在聽

curl http://localhost:11434/api/version

{"version":"0.40.3"}

有回來就代表伺服器開著。連不上的話，Mac 和 Windows 先確認 Ollama 有沒有在執行，Linux 可以手動下 ollama serve。

最簡單的一種：給一句話，拿一段回答

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:4b-instruct",
  "prompt": "用一句話說明什麼是 API。",
  "stream": false
}'

回來的是一包 JSON。我把中間一長串叫 context 的數字拿掉，其他原樣：

{
  "model": "qwen3:4b-instruct",
  "created_at": "2026-10-12T16:10:25.435970636Z",
  "response": "API 是一種讓不同軟體系統之間能夠互相通訊和交換資料的接口。",
  "done": true,
  "done_reason": "stop",
  "total_duration": 10748480987,
  "load_duration": 6813801671,
  "prompt_eval_count": 16,
  "prompt_eval_cached_count": 0,
  "prompt_eval_duration": 777948000,
  "eval_count": 20,
  "eval_duration": 3141502000
}

答案在 response。順帶一提，它把 interface 講成「接口」，台灣的說法是「介面」。

後面那幾個數字是統計。時間的單位是奈秒，所以 total_duration 是 10.7 秒，其中 load_duration 的 6.8 秒是在把模型載進記憶體，第二次呼叫就不用再等。prompt_eval_count 是讀進去的 token 數，eval_count 是產生的 token 數。20 個 token 花了 3.1 秒，換算每秒大約 6 個。

我實際送的時候多帶了一個 options，把溫度設成 0、長度上限設成 60，寫法在後面。這篇的每個請求我也都加了 -H "Content-Type: application/json" 這個標頭，為了好讀，下面的範例省略了。聊天那個端點我試過不加，一樣會通。

有角色的對話：/api/chat

/api/generate 適合一次性的任務。要做對話，用 /api/chat。它吃的是一串訊息，每則訊息有角色：system 是你給它的規矩，user 是使用者，assistant 是它自己。

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:4b-instruct",
  "stream": false,
  "messages": [
    {"role": "system", "content": "你是客服，回答要簡短，一律用繁體中文。"},
    {"role": "user", "content": "我叫小明。"},
    {"role": "assistant", "content": "你好，小明。"},
    {"role": "user", "content": "我叫什麼名字？"}
  ]
}'

回應裡，答案的位置換成了 message.content：

"message": {"role": "assistant", "content": "你叫小明。"}

它不會記得你

上面那個請求裡，前兩句對話是我自己放進去的。這是 API 跟聊天畫面最大的差別：伺服器不存對話，每個請求都是獨立的。

我把前兩句拿掉，只留規矩和最後那個問題，再送一次。它回的是：「我無法知道你的名字。」

所以要它記得前面講過什麼，你的程式得自己把對話存起來，每次連同新的問題一起送。代價是越聊越長。帶著那兩句對話的請求，讀進去的是 52 個 token，沒帶的是 32 個。

串流：不寫 stream，它就一個字一個字回

前面每個請求我都寫了 "stream": false。拿掉的話，回來的東西長這樣：

{"model":"qwen3:4b-instruct","created_at":"2026-10-12T16:10:26.16919049Z","message":{"role":"assistant","content":"早"},"done":false}
{"model":"qwen3:4b-instruct","created_at":"2026-10-12T16:10:26.33798572Z","message":{"role":"assistant","content":"安"},"done":false}
{"model":"qwen3:4b-instruct","created_at":"2026-10-12T16:10:26.495929326Z","message":{"role":"assistant","content":"！"},"done":false}

一行一個 JSON，一行一小段字。我問它「用一句話跟我說早安」，總共回來 21 行。最後一行的 done 是 true，統計數字都放在那一行。

串流是預設值，適合做聊天畫面，使用者不用盯著空白等。寫腳本、接自動化流程的話，一次拿完比較好處理，記得加 "stream": false。沒注意到這個預設值，程式會壞得莫名其妙：它預期拿到一包 JSON，結果拿到二十幾包。

常用的參數

調整模型行為的參數放在 options 裡。這幾個我都用過：

"options": {
  "temperature": 0,
  "seed": 42,
  "num_predict": 100,
  "num_ctx": 16384
}

temperature 設成 0，它每次都挑最有把握的字，回答比較穩定，我做測試的時候都這樣設。seed 是亂數的種子。num_predict 是最多產生幾個 token，用來防止它講個不停。num_ctx 是 context 的長度，沒有顯卡時預設只有 4096。

另外有兩個參數寫在 options 外面，跟 model 同一層。

think 控制會思考的模型要不要先推理。設成 false 可以省下很多時間，但不是每個模型都理它，我踩過的坑寫在Qwen3 那篇。

keep_alive 控制模型在記憶體裡留多久。設成 0 會立刻卸載：

curl http://localhost:11434/api/generate -d '{"model": "qwen3:4b-instruct", "keep_alive": 0}'

回應的 done_reason 會是 unload。

要它回 JSON

接自動化流程的時候，你通常不要一段話，要的是可以直接拿來用的資料。加一個 format 就可以。

最簡單的寫法是 "format": "json"。我問它台灣常見的三種水果，回來的 content 是：

{
  "fruits": [
    "鳳梨",
    "芭樂",
    "芒果"
  ]
}

欄位叫什麼名字是它自己決定的。要連欄位都指定，就把 format 換成一份 JSON schema：

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:4b-instruct",
  "stream": false,
  "options": {"temperature": 0},
  "messages": [{"role": "user", "content": "用 JSON 告訴我台北市的資料：城市名稱、所在國家或地區、人口大約幾百萬。"}],
  "format": {
    "type": "object",
    "properties": {
      "city": {"type": "string"},
      "region": {"type": "string"},
      "population_million": {"type": "number"}
    },
    "required": ["city", "region", "population_million"]
  }
}'

回來的是：

{
  "city": "台北市",
  "population_million": 250,
  "region": "台灣"
}

格式完全照我的要求，三個欄位都在，型別也對。但你看那個數字。我問的是幾百萬，台北市大約 250 萬人，正確的答案是 2.5，它寫了 250。

這是我想讓你記住的一件事：指定格式只保證格式，不保證內容。程式不會報錯，資料會安靜地錯下去。重要的數字要另外檢查。

工具呼叫

工具呼叫是讓模型知道「你有這些功能可以用」，由它決定要不要用、參數填什麼。它自己不會執行，是把要求丟回來給你的程式。

我定義了一個查天氣的工具，然後問它台北的天氣：

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:4b-instruct",
  "stream": false,
  "messages": [{"role": "user", "content": "台北現在天氣怎麼樣？"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查詢某個城市現在的天氣",
      "parameters": {
        "type": "object",
        "required": ["city"],
        "properties": {"city": {"type": "string", "description": "城市名稱"}}
      }
    }
  }]
}'

它沒有直接回答。content 是空的，多了一個 tool_calls：

"message": {
  "role": "assistant",
  "content": "",
  "tool_calls": [{
    "id": "H6vZOyPJSPvYrYUzOYMjv3YEXZgm4n67",
    "function": {"index": 0, "name": "get_weather", "arguments": {"city": "台北"}}
  }]
}

意思是：請幫我呼叫 get_weather，城市填台北。

接下來是你的程式的工作。真的去查天氣，把結果用 tool 這個角色放回對話裡，再送一次。我直接假裝查到了「28°C，晴」：

"messages": [
  {"role": "user", "content": "台北現在天氣怎麼樣？"},
  {"role": "assistant", "content": "", "tool_calls": [上一步它回的那一段]},
  {"role": "tool", "tool_name": "get_weather", "content": "28°C，晴"}
]

這次它回：「台北現在的天氣是28°C，晴天。」

兩個來回，第一次 8.5 秒，第二次 3 秒。第一次比較久，因為工具的定義也要讀，那個請求讀進去的是 163 個 token。

不是每個模型都支援工具呼叫。用 ollama show 看能力那一欄有沒有 tools。我測過的模型裡，Gemma 3 就沒有。

向量

要做搜尋或是讓模型查資料，會用到向量，也就是把一段文字變成一串數字。這要另外抓專門的模型，我用的是官方文件推薦的 embeddinggemma，621 MB。

curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": ["今天天氣很好", "今天是晴天", "我想吃牛肉麵"]
}'

回來三個向量，每個是 768 個數字。

這些數字的用途是比較相似度。我把第一句分別跟另外兩句算了一下：「今天天氣很好」跟「今天是晴天」是 0.87，跟「我想吃牛肉麵」是 0.38。意思相近的句子，分數比較高。

用 Python

Ollama 有官方的 Python 函式庫：

pip install ollama

from ollama import chat

r = chat(model='qwen3:4b-instruct',
         messages=[{'role': 'user', 'content': '用一句話跟我說早安。'}],
         options={'temperature': 0, 'num_predict': 40})
print(r.message.content)
print(r.prompt_eval_count, r.eval_count)

我跑出來的是：

早安！願你的一天充滿陽光、笑容與美好機遇！☀️😊
16 21

我裝到的版本是 0.6.3。我是在 Ubuntu 上先用 python3 -m venv 開一個虛擬環境，再裝進去的。

相容 OpenAI 和 Anthropic 的介面

如果你的程式本來是接 OpenAI 的，不用重寫。Ollama 另外開了一組跟 OpenAI 格式相同的網址，在 /v1 底下：

from openai import OpenAI

client = OpenAI(base_url='http://localhost:11434/v1', api_key='ollama')
r = client.chat.completions.create(
    model='qwen3:4b-instruct',
    messages=[{'role': 'user', 'content': '用一句話跟我說晚安。'}],
    temperature=0, max_tokens=40)
print(r.choices[0].message.content)

api_key 一定要填，但填什麼都可以。回來的格式跟 OpenAI 一樣，有 choices，也有 usage。GET /v1/models 會列出你下載的模型。

有些工具的設定畫面只給「OpenAI 相容」這個選項，這時候填這組網址就可以。

它也有 Anthropic 格式的 /v1/messages。我照 Anthropic 的格式送了一個請求，回來的是 {"type":"message", ...}，內容放在 content[0].text。官方文件說 Claude Code 可以透過這個介面改用 Ollama 的模型，這個我沒有試。

讓別台電腦連進來

預設只有這台電腦自己連得到。我在測試機上看它監聽的位址：

LISTEN 0      4096       127.0.0.1:11434      0.0.0.0:*

要讓同一個網路的其他電腦連進來，啟動的時候加環境變數：

OLLAMA_HOST=0.0.0.0:11434 ollama serve

重開之後，監聽的位址變成 *:11434。Mac、Windows 和用系統服務啟動的 Linux，設環境變數的方式不一樣，官方文件的 FAQ 有分別寫，那幾種我沒有測。

本機的 API 沒有任何驗證。連得到那個 port 的人，都可以用你的模型、佔你的機器。開給家裡或公司內部的網路可以，不要直接開到公開的網路上。

網頁要從瀏覽器直接呼叫的話，還會遇到跨來源的限制，官方文件說要另外設 OLLAMA_ORIGINS。這個我也沒有測。

出錯的時候長什麼樣子

錯誤一樣是 JSON，訊息放在 error，同時看 HTTP 狀態碼。我故意弄錯三次：

這幾個訊息都很直白。比較麻煩的是記憶體不夠的時候，錯誤訊息不一定會提到記憶體，我在Gemma 4 硬體需求遇過一次。

管理模型的幾個端點

GET /api/tags 列出已經下載的模型，包含大小、參數量、量化方式。

GET /api/ps 列出現在載在記憶體裡的模型，還有它什麼時候會被卸載。

POST /api/show 帶模型名字，會回傳它的細節，包含支不支援工具呼叫、看圖、思考。

接下來

API 會用之後，模型挑哪一個就變得更重要，因為程式不像人，不會發現它答錯。我拿十個小模型問過同一組題目，結果在Ollama 模型推薦。

上面的工具呼叫，是自己寫程式來回傳結果。n8n 的 AI Agent 節點把這一圈包好了：接上 Ollama 和幾個工具，它會自己呼叫、自己把結果交回模型，實際做一次的過程在 n8n AI Agent 教學。