AI workflow thất bại: làm sao biết lỗi do model, prompt, dữ liệu hay API?

Muốn biết AI workflow thất bại do model, prompt, dữ liệu hay API, đừng bắt đầu bằng việc đổi model hoặc viết lại prompt. Hãy giữ lại một execution có thể tái hiện, chia trace theo từng lớp và thay đúng một biến trong mỗi lần replay. Nếu request chưa tới model, đó không phải lỗi model. Nếu model trả đúng nhưng bước parse hoặc API đích thất bại, sửa prompt cũng không giải quyết được.

Một quy trình chẩn đoán đáng tin cậy gồm bốn bước: xác định điểm thất bại đầu tiên → phân loại lỗi kỹ thuật hay lỗi chất lượng → replay bằng input đã đóng băng → chạy test đối chứng cho từng giả thuyết. Ngoài bốn lớp thường được nhắc tới, production còn có lớp thứ năm là orchestration/state: mapping, branch, queue, timeout, retry, parser hoặc lưu trạng thái có thể làm run hỏng dù model và API đều hoạt động đúng.

Một taxonomy vận hành nên có ít nhất năm nhóm:

1. Orchestration: workflow không chạy đúng đường đi dự kiến; expression lỗi, item bị mất khi merge, parser ném exception, queue chờ quá lâu, state chuyển sai hoặc retry tạo kết quả trùng.
2. API/provider: DNS, TLS, authentication, quota, rate limit, timeout, lỗi 4xx/5xx, response rỗng hoặc contract của provider thay đổi. Nhóm này gồm API model và các API/tool bên ngoài.
3. Data/context: input thiếu trường, sai type/encoding, quá dài, tài liệu retrieval không liên quan, dữ liệu cũ, OCR lỗi, tenant filter sai hoặc context bị cắt.
4. Prompt/contract: chỉ dẫn mơ hồ hay xung đột, ví dụ thiếu, output schema không rõ, tool description chồng lấn hoặc prompt version không tương thích với bước downstream.
5. Model: model không đủ khả năng cho tác vụ, không tuân thủ format ổn định, chọn sai tool dù candidate set rõ, hoặc chất lượng giảm sau thay đổi model/version.

Một run có thể chứa nhiều lỗi nối tiếp. Root cause là điểm sai đầu tiên tạo ra chuỗi hậu quả, không nhất thiết là node cuối cùng báo đỏ.

Dấu hiệu quan sát được	Nghi ngờ đầu tiên	Cần kiểm tra
Request không rời workflow hoặc sai branch	Orchestration	Input/output từng node, expression, state transition, queue và timeout
401/403	Credential, scope hoặc policy	Secret version, audience, token expiry và quyền resource
429 hoặc latency tăng theo lưu lượng	Provider/API capacity	Rate-limit headers, retry-after, concurrency, quota và backoff
400/422	Request contract	Endpoint, model name, schema, field type, payload size
Model trả 200 nhưng output không parse được	Prompt/schema hoặc parser	Raw response, finish reason, structured-output contract, truncation
Chỉ lỗi với một nhóm khách hàng/tài liệu	Data/context	Tenant, locale, encoding, missing fields, retrieval result
Cùng input và prompt nhưng model đối chứng tốt hơn ổn định	Model capability/version	Eval set, model/deployment ID, nhiều lần chạy đối chứng
Model output đúng nhưng action cuối sai	Mapping, business rule hoặc API/tool	Arguments trước/sau transform, authorization và API response

Các dấu hiệu này là điểm bắt đầu, không phải kết luận. Ví dụ 400 từ model API có thể do orchestration tạo sai payload; output sai format có thể do context bị cắt chứ không phải prompt kém.

Dùng thứ tự sau cho mỗi incident:

1. Execution có bắt đầu và đi đúng branch không? Nếu không, điều tra trigger, filter, expression, queue và state.
2. Lời gọi ra ngoài có hoàn tất về mặt kỹ thuật không? Ghi status code, error code, latency, attempt, timeout và provider request ID.
3. Payload có đúng contract không? Validate schema trước và sau mỗi transform; lưu hash/version của input thay vì chỉ nhìn giao diện.
4. Model có nhận đúng prompt và context không? Kiểm tra prompt version, model/deployment, system instruction, tool definitions, token usage, finish reason và tài liệu retrieval thực sự được chèn.
5. Raw model output có đạt contract không? Tách parse/schema validation khỏi đánh giá nội dung.
6. Downstream có dùng đúng output không? So sánh model output với payload gửi API/tool và postcondition đọc lại từ hệ thống đích.
7. Nếu kỹ thuật đều pass, chất lượng có đạt rubric không? Chạy eval về correctness, relevance, groundedness hoặc business rule theo use case.

Luôn giữ raw evidence có kiểm soát truy cập. Screenshot một node thường không đủ để chứng minh dữ liệu trước và sau transform giống nhau.

Mỗi execution cần một trace_id xuyên suốt workflow và span cho trigger, transform, retrieval, model call, tool/API call, validation và persistence. AWS khuyến nghị structured logs có correlation ID và metric theo từng lớp; OpenTelemetry đã định nghĩa các thuộc tính GenAI như provider, request/response model, token usage, finish reason, tool call và retrieval documents.

Tối thiểu nên ghi: workflow_version, node_version, prompt_version, model_requested, model_returned, provider/deployment/region, input schema version, input hash, retrieval document IDs và scores, tool schema version, attempt, timeout, status/error code, latency, token usage, output schema result và business postcondition. Với API ngoài, giữ request ID của provider và response headers cần thiết cho rate limit.

Không mặc định ghi toàn bộ prompt, output, tool arguments hoặc tài liệu vào log. OpenTelemetry cảnh báo các trường này có thể chứa PII hoặc dữ liệu nhạy cảm. Áp dụng allowlist, redaction/tokenization, mã hóa, RBAC, retention ngắn và audit truy cập. Khi cần replay, dùng snapshot đã khử nhạy cảm hoặc kho bằng chứng được kiểm soát, không copy dữ liệu production sang môi trường test tùy tiện.

Từ execution lỗi, tạo một test case bất biến gồm input đã chuẩn hóa, context/retrieval snapshot, prompt version, tool definitions, expected schema và expected business outcome. Sau đó chạy ma trận:

• Baseline replay: cùng model, prompt, data snapshot và mock API. Nếu không tái hiện, kiểm tra nondeterminism, provider version, caching và state bên ngoài.
• Prompt test: giữ model/data cố định, chỉ dùng prompt candidate. Nếu nhiều test case cải thiện mà không gây regression, giả thuyết prompt được củng cố.
• Model test: giữ prompt/data cố định, đổi sang model đối chứng. Một lần tốt hơn chưa đủ; cần chạy eval set và so sánh theo rubric.
• Data test: giữ model/prompt cố định, thay data lỗi bằng golden input hoặc sửa đúng một defect. Nếu output phục hồi, tập trung vào ingestion, validation hoặc retrieval.
• API isolation: thay API/tool thật bằng stub đã biết response; rồi gửi chính payload đã ghi lại tới sandbox của API. Cách này tách lỗi tạo payload khỏi lỗi hệ thống đích.

Không replay action có side effect trực tiếp trên production. Dùng read-only mode, dry-run, sandbox, stub hoặc idempotency key; nếu buộc phải xác minh, cần phạm vi tài nguyên riêng và postcondition rõ ràng.

Nếu là orchestration: thêm schema gate giữa các node, state machine rõ, timeout budget, idempotency, bounded retry, DLQ và reconciliation. Không dùng continue on fail khiến lỗi bị nuốt nhưng dữ liệu vẫn đi tiếp.

Nếu là API/provider: phân loại retryable và permanent theo code; tôn trọng Retry-After; dùng exponential backoff có jitter, circuit breaker, quota alert và fallback chỉ khi semantic contract tương đương. Lỗi auth hoặc schema không nên retry mù.

Nếu là dữ liệu/context: validate bắt buộc, type, encoding, kích thước, tenant và freshness ngay khi ingest; lưu lineage; đo retrieval hit rate, relevance và empty-context rate; quarantine input bất thường.

Nếu là prompt/contract: version prompt như code; tách instruction khỏi dữ liệu không tin cậy; dùng structured output/schema; bổ sung ví dụ và negative cases; chạy regression eval trước rollout. Không vá từng câu lỗi vào prompt cho đến khi prompt trở thành danh sách ngoại lệ khó kiểm soát.

Nếu là model: chứng minh bằng eval trên tập dữ liệu đại diện; kiểm tra model/version drift, context limit, modality, latency và cost. Chỉ đổi model khi candidate vượt quality gate và không phá SLO vận hành. Với lỗi không ổn định, canary và giữ khả năng rollback deployment.

Mỗi incident đã xác nhận phải tạo ít nhất một regression case gồm sanitized input, expected branch, expected tool/API call, output schema và business outcome. n8n hỗ trợ lấy execution data trước đó để debug; data pinning/mocking giúp cố định dữ liệu khi phát triển. Với AI workflow, n8n cũng khuyến nghị evaluations thay cho kiểm tra thủ công một vài câu mẫu.

Dashboard nên tách technical reliability và AI quality. Nhóm kỹ thuật gồm workflow success rate, node error rate, API 4xx/5xx/429, timeout, queue wait, retry và p95 latency. Nhóm AI gồm schema-valid rate, task success, groundedness/correctness theo rubric, no-answer/clarification rate, tool selection và postcondition success. Luôn phân đoạn theo workflow, prompt, model, data source, tenant/use case và deployment version để phát hiện regression bị che bởi số trung bình.

Thiết lập change gate: prompt/model/tool/schema mới chỉ được canary khi eval pass; tự rollback hoặc dừng mở rộng khi error budget hay quality threshold bị vi phạm. Không đặt một SLO chung “workflow success” vì API 200 không có nghĩa câu trả lời đúng, còn một câu trả lời đúng không có nghĩa side effect đã thực thi thành công.

Triển khai thực dụng trong n8n

1. Gắn trace_id, workflow_version và input_hash ngay sau trigger; truyền chúng qua mọi sub-workflow.
2. Trước AI node, lưu prompt/model/tool/schema version và validate normalized input.
3. Sau AI node, giữ metadata kỹ thuật và raw response theo policy; chạy parser cùng schema validator ở node riêng.
4. Bao mỗi HTTP/tool call bằng lớp chuẩn hóa error: layer, code, retryable, attempt, provider_request_id và safe_message.
5. Dùng Error Workflow để đẩy incident envelope vào nơi theo dõi; không gửi credential, raw PII hay toàn bộ prompt qua Slack/email.
6. Với execution lỗi, copy data sang workflow test, pin/mask input, stub các side-effect API và replay theo ma trận một biến.
7. Tách dashboard theo stage: ingest, retrieval, model, validation, action và verification.
8. Khi sửa xong, thêm case vào evaluation dataset và CI gate trước khi activate version mới.

Mẫu incident envelope nên trả lời được: run nào; lỗi đầu tiên ở span nào; input/prompt/model/tool version nào; có tái hiện không; giả thuyết nào đã bị loại; bản sửa nào; regression test nào bảo vệ về sau. Đây là nền tảng để giảm thời gian xử lý sự cố mà không biến log thành kho dữ liệu nhạy cảm.