Quy trình phê duyệt thủ công n8n với API tương thích OpenAI và xác thực JSON Schema

Quyết định: phê duyệt hành động, không chỉ phê duyệt việc trích xuất

Đối với hóa đơn, phiếu hỗ trợ, biểu mẫu và yêu cầu gửi đến, phần rủi ro thường không nằm ở việc trích xuất các trường dữ liệu. Rủi ro nằm ở những gì xảy ra sau đó: tạo bản ghi khách hàng, thay đổi trạng thái, gửi tin nhắn ra bên ngoài hoặc xóa dữ liệu.

Vì vậy, một thiết kế n8n vững chắc sử dụng ba lớp kiểm soát:

1. Trích xuất: API tương thích OpenAI trả về dữ liệu có cấu trúc.
2. Xác thực: n8n kiểm tra dữ liệu có tuân thủ JSON Schema hay không.
3. Phê duyệt: n8n AI Agent chỉ có thể gọi một công cụ có hậu quả sau khi được một người phê duyệt.

Cách này ngăn dữ liệu không hợp lệ đến tay người duyệt và tách biệt việc thực thi đã được phê duyệt khỏi đầu ra của mô hình.

OneMux cung cấp quyền truy cập vào các mô hình AI hàng đầu thông qua một API tương thích OpenAI duy nhất. Bạn có thể sử dụng OneMux làm tuyến truy cập mô hình nếu endpoint và mô hình đã chọn có tài liệu xác nhận hỗ trợ định dạng yêu cầu và các tham số mà cấu hình n8n của bạn cần. Bài viết này không tuyên bố rằng tích hợp OneMux và n8n đã được kiểm thử.

Điều kiện tiên quyết

Bạn cần có:

• Một instance n8n có quyền truy cập vào các node HTTP Request, Code và, khi phù hợp, AI Agent.
• Một kênh phê duyệt được thiết lập n8n hỗ trợ, chẳng hạn như n8n Chat, Slack, Telegram, email hoặc một kênh khác được tài liệu hóa.
• Quyền truy cập vào API tương thích OpenAI. Nếu sử dụng OneMux, hãy bắt đầu với hướng dẫn nhanh OneMux và xác nhận endpoint hiện tại, phương thức xác thực, mã định danh mô hình và các tham số yêu cầu được hỗ trợ trong tài liệu OneMux.
• Một JSON Schema mô tả đối tượng bạn muốn trích xuất.
• Một công cụ đích, chẳng hạn như thao tác cập nhật CRM hoặc gửi tin nhắn, không được phép chạy nếu chưa có người xem xét.

Không nên giả định rằng mọi endpoint tương thích OpenAI đều hỗ trợ mọi tính năng xuất dữ liệu có cấu trúc. Hãy xác minh khả năng hỗ trợ response_format, JSON Schema, lệnh gọi công cụ và mô hình cụ thể bạn chọn. Danh mục mô hình OneMux có thể giúp bạn xem xét các lựa chọn mô hình hiện có, nhưng bản thân danh mục này không chứng minh khả năng hỗ trợ một cấu hình node n8n cụ thể.

Quy trình n8n được đề xuất

Một quy trình thực tiễn có thể sử dụng các node sau:

1. Webhook hoặc một trigger khác nhận văn bản nguồn.
2. HTTP Request gửi văn bản đến endpoint mô hình tương thích.
3. Code phân tích cú pháp và xác thực đối tượng trả về.
4. IF chuyển các kết quả không hợp lệ sang nhánh lỗi hoặc nhánh chỉnh sửa thủ công.
5. AI Agent nhận đối tượng đã xác thực và có quyền truy cập vào một công cụ có hậu quả.
6. Xem xét thủ công tạm dừng quy trình trước khi công cụ đó chạy.
7. Công cụ đã được phê duyệt ghi bản ghi hoặc gửi tin nhắn.

Yêu cầu trích xuất chỉ nên bao gồm những trường mà quy trình của bạn cần. Một ví dụ schema ngắn gọn cho yêu cầu hỗ trợ có thể như sau:

{
  "$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"
    }
  }
}

Cấu hình yêu cầu tương thích OpenAI

Trong node HTTP Request, hãy sử dụng base URL và hướng dẫn xác thực từ tài liệu của nhà cung cấp. Không hard-code URL dành riêng cho nhà cung cấp trừ khi bạn đã xác minh URL đó phù hợp với tài khoản và khu vực của mình.

Cấu trúc yêu cầu dưới đây chỉ mang tính minh họa. Việc response_format và cấu trúc JSON Schema của nó có được chấp nhận hay không phụ thuộc vào endpoint, mô hình và cấu hình n8n bạn chọn.

{
  "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"}
        }
      }
    }
  }
}

Ví dụ cố ý sử dụng một model ID giữ chỗ. Hãy chọn một mô hình được tài liệu xác nhận là tương thích với endpoint bạn chọn. Nếu không có đầu ra JSON Schema nghiêm ngặt, chỉ sử dụng chế độ JSON được hỗ trợ khi quy trình xác thực của bạn có thể an toàn từ chối các phản hồi không tuân thủ. Chỉ chế độ JSON không tương đương với việc xác thực schema.

Xác thực phản hồi trước khi thực thi

Phản hồi từ nhà cung cấp có thể đặt nội dung được tạo trong các trường khác nhau. Hãy kiểm tra một phản hồi thực tế trong n8n trước khi viết bộ phân tích cú pháp. Node Code sau đây giả định mô hình trả về một chuỗi JSON trong message.content; hãy điều chỉnh đường dẫn cho khớp với phản hồi thực tế bạn nhận được.

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 } }];

Trong môi trường production, hãy thay thế bước kiểm tra đơn giản này bằng một trình xác thực JSON Schema được duy trì khi hạ tầng n8n của bạn cho phép. Schema trong yêu cầu và schema được áp dụng khi xác thực nên được quản lý phiên bản cùng nhau. Hãy thêm phiên bản schema vào đầu ra nếu các hệ thống tiếp theo cần phân biệt các bản sửa đổi.

Thêm phê duyệt thủ công cho công cụ AI Agent

Sử dụng đối tượng đã xác thực làm ngữ cảnh cho AI Agent. Cấp cho Agent một công cụ có phạm vi hẹp, chẳng hạn như CreateSupportTicket, thay vì quyền truy cập cơ sở dữ liệu rộng. Cấu hình tính năng xem xét thủ công cho công cụ đã chọn trong Tools Panel của AI Agent.

Tài liệu n8n nêu rằng quy trình sẽ tạm dừng khi Agent cố gắng sử dụng một công cụ yêu cầu xem xét. Người duyệt có thể phê duyệt lệnh gọi, cho phép công cụ thực thi với dữ liệu đầu vào được đề xuất, hoặc từ chối lệnh gọi, qua đó hủy hành động. n8n hỗ trợ nhiều kênh phê duyệt, bao gồm giao diện chat tích hợp và các tích hợp như Slack, Telegram, Discord, Teams, email, WhatsApp, Google Chat và Outlook email. Xem tài liệu chính thức về human-in-the-loop của n8n để biết các bước thiết lập và thông tin kênh hiện tại.

Một thông báo phê duyệt hữu ích nên hiển thị hành động và các tham số được đề xuất:

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

Tài liệu nguồn xác định $tool.name và $tool.parameters cho ngữ cảnh xem xét này. Hãy trình bày thông báo dễ đọc và bao gồm yêu cầu ban đầu hoặc mã tham chiếu phiếu khi người duyệt cần thêm ngữ cảnh.

System prompt của Agent cũng nên giải thích cách xử lý việc xem xét:

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.

Giới hạn và khắc phục sự cố

Mô hình trả về Markdown hoặc văn bản thừa

Kiểm tra xem endpoint có hỗ trợ các tham số đầu ra có cấu trúc mà bạn đã gửi hay không. Nếu không, hãy xóa các tham số không được hỗ trợ, làm rõ chỉ dẫn và tiếp tục dùng bước xác thực trong node Code như một lớp kiểm soát bắt buộc. Không bao giờ gửi đối tượng chưa được xác thực đến công cụ ghi dữ liệu.

n8n không tìm thấy trường phản hồi dự kiến

Kiểm tra đầu ra của HTTP Request và cập nhật bộ phân tích cú pháp. Các API tương thích OpenAI có thể dùng chung quy ước yêu cầu nhưng vẫn khác nhau về chi tiết phản hồi và các tham số được hỗ trợ.

Yêu cầu phê duyệt quá mơ hồ

Sử dụng một công cụ có phạm vi hẹp và đưa $tool.name cùng $tool.parameters vào thông báo phê duyệt. Không yêu cầu người duyệt phê duyệt một chỉ dẫn không rõ nội dung như “xử lý yêu cầu này”.

Lệnh gọi công cụ bị từ chối gây ra vòng lặp

Thêm hành vi từ chối rõ ràng vào system prompt của Agent và cấu hình quy trình để việc từ chối kết thúc nhánh hành động hoặc chuyển sang bước làm rõ. Tài liệu n8n khuyến nghị giải thích công cụ nào cần phê duyệt và Agent nên phản hồi thế nào khi bị từ chối.

Người duyệt phê duyệt dữ liệu không chính xác

Tính hợp lệ của schema không chứng minh tính chính xác về ngữ nghĩa. Hãy hiển thị cùng nhau đoạn trích nguồn, các trường đã trích xuất và hành động dự kiến. Đối với quy trình có tác động lớn, hãy yêu cầu người duyệt xác nhận độc lập các trường nhạy cảm.

Kết luận

Mẫu n8n an toàn nhất cho việc trích xuất dữ liệu có cấu trúc không phải là “để mô hình ghi trực tiếp”. Hãy trích xuất thành một đối tượng có ràng buộc, xác thực đối tượng đó, rồi đặt phê duyệt thủ công trước công cụ có thể thay đổi thế giới bên ngoài. API tương thích OpenAI có thể đơn giản hóa việc truy cập mô hình, còn n8n cung cấp khả năng điều phối và kiểm soát phê duyệt. Với OneMux, hãy sử dụng endpoint và tham số mô hình tương thích được tài liệu hóa, xác minh cấu hình trong môi trường của riêng bạn và xem các tính năng đầu ra có cấu trúc không được hỗ trợ là lý do để dừng hoặc chuyển sang một quy trình phản hồi được xác thực riêng.