農業生成式 AI 服務平台

Gemma 4 API 介接說明手冊

本文件旨在提供技術人員如何透過 API 介接本單位的 Gemma 4 生成式 AI 服務。本平台後端採用 vLLM 引擎，提供與 OpenAI 完全相容的 RESTful API 介面，支援文字對話（Chat）與視覺辨識（Vision）功能。

所有 API 請求均須透過 Nginx 網關加密傳輸。

1. 基礎連線資訊 (Endpoint)

項目	內容	說明
基礎網址 (Base URL)	`https://172.28.15.11/v1`	採用標準 HTTPS 加密埠號 (443)
API 金鑰 (Bearer Token)	`[API Key]`	須放在 HTTP Header 的 `Authorization` 欄位
模型 ID (Model ID)	`gemma-4-31b`	注意小寫與連字號

2. 重要資安與連線規範

⚠️ SSL 憑證警告：由於目前使用機房內部自簽憑證，程式呼叫時預設會觸發安全警告。請依據使用的工具進行調整：

cURL：請加上 -k 或 --insecure 參數。
Python：使用 verify=False。
Node.js：設定 process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'。

傳輸大小限制	單次請求（含圖片 Base64 編碼）上限為 20MB。
語系強制優化	為確保模型回覆繁體中文，建議在對話中加入 `system` 角色設定。

3. 文字對話範例 (Text Generation)

cURL (Windows CMD 快速測試)

Bash

curl -k https://172.28.15.11/v1/chat/completions ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer [YOUR_API_KEY]" ^
  -d "{\"model\": \"gemma-4-31b\", \"messages\": [{\"role\": \"system\", \"content\": \"你是一個專業的農業助手，請使用台灣繁體中文回答。\"}, {\"role\": \"user\", \"content\": \"如何進行農地資源盤查？\"}]}"

4. 視覺辨識範例 (Image Analysis)

A. 使用 cURL

首先將圖片轉為 Base64 (可用網頁工具或 PowerShell)。建立 payload.json 檔案：

JSON

{
  "model": "gemma-4-31b",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "請描述圖片中的農作物狀況。" },
        { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,[貼上你的 Base64 字串]" } }
      ]
    }
  ]
}

執行發送命令：

Bash

curl -k https://172.28.15.11/v1/chat/completions ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer [YOUR_API_KEY]" ^
  -d @payload.json

B. 使用 Python (自動化處理)

Python

import base64
import requests

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

api_key = "你的API_KEY"
image_path = "crop_photo.jpg"
base64_image = encode_image(image_path)

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}"
}

payload = {
    "model": "gemma-4-31b",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "請以繁體中文分析此張農地照片。"},
                {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}}
            ]
        }
    ]
}

response = requests.post("https://172.28.15.11/v1/chat/completions", headers=headers, json=payload, verify=False)
print(response.json()['choices'][0]['message']['content'])

5. 常見問題排除 (Troubleshooting)

錯誤代碼	可能原因	解決方法
404 Not Found	Model ID 拼錯	確認模型名稱是否完整且正確為 `gemma-4-31b`（注意連字號 `-`）。
401 Unauthorized	Token 錯誤或過期	檢查 Authorization Header 是否包含 `Bearer` 前綴與正確的 Key。
SSL Handshake Failed	憑證驗證失敗	確保程式已設定「忽略 SSL 驗證 (Skip/Ignore SSL Certification)」，例如 cURL 需加上 `-k`。
504 Gateway Timeout	圖片太大或模型運算過久	減少圖片解析度，或聯繫管理員調整 Nginx 超時設定。