使用 OpenAI-Compatible API 與 JSON Schema 驗證建立 n8n 人工核准工作流程

決策重點：核准動作，而不只是核准資料擷取

對於發票、支援工單、表單與傳入請求而言，風險通常不在於擷取欄位，而在於後續會發生什麼事：建立客戶紀錄、變更狀態、傳送外部訊息，或刪除資料。

因此，穩健的 n8n 設計會使用三道關卡：

1. 擷取： OpenAI-Compatible API 返回結構化資料。
2. 驗證： n8n 檢查資料是否符合 JSON Schema。
3. 核准： n8n AI Agent 只有在人員核准後，才能呼叫會產生重要影響的工具。

這樣可以避免格式錯誤的資料送到審核者面前，也能讓核准後的執行與模型輸出彼此分離。

OneMux 透過單一 OpenAI-Compatible API 提供主流 AI 模型的存取能力。如果 endpoint 與所選模型的文件確認支援 n8n 設定所需的請求格式與參數，便可將其作為模型存取路徑。本文不主張 OneMux 與 n8n 的整合已經過測試。

事前準備

你需要：

• 一個可使用 HTTP Request、Code，以及在適用情況下使用 AI Agent 節點的 n8n 執行個體。
• 一個 n8n 設定支援的核准管道，例如 n8n Chat、Slack、Telegram、電子郵件或其他有文件說明的管道。
• 一個 OpenAI-Compatible API 的存取權限。如果使用 OneMux，請先參考 OneMux quickstart，並在 OneMux documentation 中確認目前的 endpoint、驗證方式、模型識別碼與支援的請求參數。
• 一份描述要擷取之物件的 JSON Schema。
• 一個不應在沒有人工審核的情況下執行的目的地工具，例如更新 CRM 或傳送訊息的動作。

不要假設每個 OpenAI-Compatible endpoint 都支援所有結構化輸出功能。請確認 response_format、JSON Schema、工具呼叫，以及你所選特定模型的支援情況。OneMux models directory 可協助你查看可用的模型選項，但這本身並不能證明特定 n8n 節點設定受到支援。

建議的 n8n 工作流程

實務上的工作流程可以使用以下節點：

1. Webhook 或其他觸發器接收來源文字。
2. HTTP Request 將文字傳送至相容模型 endpoint。
3. Code 解析並驗證返回的物件。
4. IF 將無效結果導向錯誤處理或人工修正路徑。
5. AI Agent 接收已驗證的物件，並取得一個會產生重要影響的工具。
6. 人工審核 在工具執行前暫停工作流程。
7. 已核准的工具 寫入紀錄或傳送訊息。

擷取請求應只要求工作流程真正需要的欄位。以下是一個支援請求的精簡範例 schema：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": ["category", "priority", "summary", "customer_email"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account", "other"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high", "urgent"]
    },
    "summary": {
      "type": "string",
      "minLength": 1
    },
    "customer_email": {
      "type": "string",
      "format": "email"
    }
  }
}

設定 OpenAI-Compatible 請求

在 HTTP Request 節點中，使用供應商文件所提供的 base URL 與驗證指示。除非已針對你的帳戶與區域確認過，否則不要硬式編碼供應商專用 URL。

以下請求格式僅供說明。是否接受 response_format 及其 JSON Schema 結構，取決於你選擇的 endpoint、模型與 n8n 設定。

{
  "model": "YOUR_DOCUMENTED_MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "Extract the requested fields. Do not guess missing values. Return only an object matching the supplied schema."
    },
    {
      "role": "user",
      "content": "{{$json.source_text}}"
    }
  ],
  "temperature": 0,
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_request",
      "strict": true,
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["category", "priority", "summary", "customer_email"],
        "properties": {
          "category": {"type": "string"},
          "priority": {"type": "string"},
          "summary": {"type": "string"},
          "customer_email": {"type": "string"}
        }
      }
    }
  }
}

範例刻意使用 placeholder model ID。請選擇文件明確標示與所選 endpoint 相容的模型。如果無法使用嚴格的 JSON Schema 輸出，只有在驗證路徑能安全拒絕不符合規範的回應時，才使用受支援的 JSON mode。JSON mode 本身不等同於 schema 驗證。

在執行前驗證回應

供應商的回應可能會將生成內容放在不同欄位中。在撰寫 parser 前，先在 n8n 檢查一個實際回應。以下 Code 節點假設模型在 message.content 中返回 JSON 字串；請依照實際收到的回應調整路徑。

const raw = $json.choices?.[0]?.message?.content;

if (typeof raw !== 'string') {
  throw new Error('Model response did not contain message.content as a string');
}

let extracted;
try {
  extracted = JSON.parse(raw);
} catch (error) {
  throw new Error('Model returned invalid JSON');
}

const required = ['category', 'priority', 'summary', 'customer_email'];
const missing = required.filter((key) => extracted[key] === undefined || extracted[key] === '');

const validCategory = ['billing', 'technical', 'account', 'other'].includes(extracted.category);
const validPriority = ['low', 'normal', 'high', 'urgent'].includes(extracted.priority);
const validEmail = typeof extracted.customer_email === 'string' &&
  /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(extracted.customer_email);

if (missing.length || !validCategory || !validPriority || !validEmail) {
  throw new Error('Extracted object failed application validation');
}

return [{ json: { extracted } }];

在正式環境中，請在 n8n 部署允許的情況下，使用受維護的 JSON Schema 驗證器取代這個輕量檢查。請讓請求中的 schema 與驗證時採用的 schema 一起進行版本管理。如果下游系統需要區分不同版本，請在輸出中加入 schema 版本。

將人工核准加入 AI Agent 工具

將已驗證的物件作為 AI Agent 的上下文。為 Agent 提供範圍明確的工具，例如 CreateSupportTicket，而不是廣泛的資料庫存取權限。在 AI Agent 的 Tools Panel 中，針對該選定工具設定人工審核。

n8n 文件指出，當 Agent 嘗試使用需要審核的工具時，工作流程會暫停。審核者可以核准呼叫，讓工具依照提出的輸入執行，也可以拒絕呼叫，取消該動作。n8n 支援多種核准管道，包括內建聊天介面，以及 Slack、Telegram、Discord、Teams、電子郵件、WhatsApp、Google Chat 和 Outlook email 等整合。請參考官方的 n8n human-in-the-loop documentation，取得目前的設定步驟與管道詳細資訊。

實用的核准訊息應呈現預定執行的動作與參數：

The AI wants to use {{ $tool.name }} with the following parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

來源文件針對此審核上下文指定了 $tool.name 與 $tool.parameters。請讓訊息易於閱讀；如果審核者需要更多上下文，也請加入原始請求或工單參考資訊。

你的 Agent system prompt 也應說明審核行為：

The CreateSupportTicket tool requires human approval. If approval is denied, do not retry automatically. Tell the user that the action was not completed and explain what information or correction is needed.

限制與疑難排解

模型返回 Markdown 或額外文字

確認 endpoint 是否支援你傳送的結構化輸出參數。如果不支援，請移除不受支援的參數、收緊指示，並保留 Code 節點驗證作為硬性關卡。絕不要將未經驗證的物件傳送給寫入工具。

n8n 找不到預期的回應欄位

檢查 HTTP Request 的輸出並更新 parser。OpenAI-Compatible API 可能共用請求慣例，但在回應細節與支援的參數上有所不同。

核准請求過於模糊

使用範圍明確的工具，並在核准訊息中加入 $tool.name 與 $tool.parameters。不要要求審核者核准「處理此請求」這類不透明的指示。

被拒絕的工具呼叫造成迴圈

在 Agent system prompt 中加入明確的拒絕處理行為，並設定工作流程，讓拒絕結束動作路徑或導向釐清流程。n8n 文件建議說明哪些工具需要核准，以及 Agent 應如何回應拒絕。

審核者核准了錯誤資料

Schema 有效並不代表語意正確。請同時顯示來源摘錄、擷取出的欄位與預定執行的動作。對於高影響工作流程，請要求審核者獨立確認敏感欄位。

結論

結構化擷取最安全的 n8n 模式不是「讓模型直接寫入」。應先將資料擷取為受約束的物件、進行驗證，再在會改變外部世界的工具前加入人工核准。OpenAI-Compatible API 可以簡化模型存取，而 n8n 則提供協調與核准控制。使用 OneMux 時，請採用文件所記載的相容 endpoint 與模型參數，在自己的環境中驗證設定，並將不受支援的結構化輸出功能視為應停止流程，或改用另一條獨立驗證回應路徑的理由。