Khả Năng Quan Sát & Truy Vết Đường Ống

Mọi tin nhắn khách hàng đến Trợ Lý Bán Hàng của bạn đều kích hoạt một đường ống xác định với nhiều giai đoạn: trích xuất đơn hàng, quy tắc định tuyến, xử lý AI, callback và các hiệu ứng sau xử lý. QuotyAI ghi lại dữ liệu đo xa chi tiết cho từng giai đoạn để bạn có thể thấy chính xác điều gì đã xảy ra, khi nào và tại sao.

Những Gì Được Ghi Lại

Mỗi lần chạy đường ống (một tin nhắn khách hàng → một phản hồi trợ lý) tạo ra một bản ghi lần chạy với năm giai đoạn:

Khách hàng gửi tin nhắn
        ↓
┌───────────────────────────────┐
│  1. Trích Xuất Đơn Hàng       │
│  Những gì trợ lý trích xuất   │
│  từ tin nhắn                   │
└───────────────────────────────┘
        ↓
┌───────────────────────────────┐
│  2. Bộ Định Tuyến Xác Định    │
│  Chỉ thị nào đã kích hoạt,    │
│  mã được tạo, hành động,      │
│  thời lượng                   │
└───────────────────────────────┘
        ↓
┌───────────────────────────────┐
│  3. Tác Nhân AI (LLM)         │
│  Mô hình sử dụng, lượng token,│
│  xem trước phản hồi, liên kết │
│  đến dấu vết LLM đầy đủ       │
└───────────────────────────────┘
        ↓
┌───────────────────────────────┐
│  4. Callback Xác Định         │
│  Callback nào đã chạy, mã     │
│  được tạo, hành động          │
└───────────────────────────────┘
        ↓
┌───────────────────────────────┐
│  5. Hiệu Ứng Sau Xử Lý       │
│  Tệp đính kèm đã gửi, thay   │
│  đổi trạng thái, sự kiện      │
│  bàn giao                     │
└───────────────────────────────┘

Mỗi giai đoạn ghi lại thời gian bắt đầu, thời gian kết thúc, thời lượng và trạng thái (thành công / thất bại / đã bỏ qua). Lỗi được ghi nhận ở cấp độ giai đoạn mà không làm gián đoạn đường ống.

Tổng Quan Đường Ống

Từ bất kỳ tin nhắn AI nào trong giao diện hội thoại, nhấp vào nút khả năng quan sát để mở modal Khả Năng Quan Sát Trợ Lý Bán Hàng. Chế độ xem mặc định là Tổng Quan Đường Ống — một dòng thời gian dọc của tất cả năm giai đoạn cho tin nhắn đó.

Thẻ Giai Đoạn

Mỗi giai đoạn là một thẻ có thể thu gọn hiển thị:

Chấm trạng thái (xanh lá = thành công, đỏ = thất bại, xám = đã bỏ qua)
Tên giai đoạn và thời lượng
Mở rộng để xem chi tiết

Trích Xuất Đơn Hàng

Hiển thị trạng thái hội thoại đầu vào và dữ liệu đơn hàng có cấu trúc mà trợ lý đã trích xuất. Đây là dữ liệu thô mà bộ định tuyến và AI sẽ làm việc.

Bộ Định Tuyến (Tự Động Hóa Trước AI)

Liệt kê mọi chỉ thị bộ định tuyến xác định đã thực thi, cùng với:

Nội dung chỉ thị (quy tắc kinh doanh gốc)
Mã TypeScript được tạo (xem trước với tô màu cú pháp)
Các hành động đã trả về (send_message, update_state, short_circuit, v.v.)
Thời lượng và thành công/thất bại của từng chỉ thị
Liệu bộ định tuyến có short-circuit AI hay không

Mỗi chỉ thị bộ định tuyến chạy như một hàm độc lập được tạo ra. Nếu một chỉ thị thất bại, các chỉ thị còn lại vẫn tiếp tục. Thẻ hiển thị từng chỉ thị dưới dạng thẻ con có thể mở rộng để xem mã đã tạo và các hành động.

Tác Nhân AI (LLM)

Hiển thị:

Mô hình đã sử dụng (ví dụ: gpt-4o)
Lượng token đã dùng (prompt, completion, tổng cộng)
Xem trước phản hồi
Liệu có xảy ra bàn giao cho tác nhân con người hay không
Liên kết đến dấu vết LLM đầy đủ — dấu vết LangChain hoàn chỉnh với mọi lời gọi công cụ, bước chuỗi và lời gọi LLM

Nút “Xem Dấu Vết LLM Đầy Đủ” chuyển sang tab dấu vết và lọc đến dấu vết liên quan. ID dấu vết LLM được liên kết được lưu trong bản ghi lần chạy để bạn luôn có thể tham chiếu chéo.

Callback (Tự Động Hóa Sau AI)

Cấu trúc tương tự như giai đoạn bộ định tuyến — mỗi chỉ thị callback được liệt kê với mã đã tạo, hành động, thời lượng và trạng thái. Callback chạy sau phản hồi AI và không thể ảnh hưởng đến những gì đã gửi cho khách hàng.

Hiệu Ứng Sau Xử Lý

Hiển thị:

Tệp đính kèm đã gửi — chỉ thị nào đã kích hoạt từng tệp đính kèm và liệu nó có thành công hay không
Thay đổi trạng thái — so sánh trước/sau của mọi khóa trạng thái hội thoại đã bị sửa đổi
Sự kiện bàn giao — nếu lần chạy kết thúc bằng bàn giao cho tác nhân con người, kèm lý do

Dấu Vết LLM Dạng Thác Nước

Tab thứ hai trong modal khả năng quan sát hiển thị Dấu Vết LLM Dạng Thác Nước — một biểu đồ Gantt trực quan hóa mọi thứ đã xảy ra bên trong tác nhân AI:

Mỗi lời gọi LLM là một span hiển thị mô hình, token prompt, token completion và thời lượng
Mỗi lời gọi công cụ là một span hiển thị tên công cụ, đối số đầu vào và giá trị trả về
Mỗi bước chuỗi là một span hiển thị thứ tự thực thi
Các span được mã hóa màu theo loại (LLM, Công Cụ, Chuỗi, Bộ Truy Xuất, Khác)
Mở rộng bất kỳ span nào để xem đầu vào, đầu ra, thẻ và chi tiết lỗi của nó

Thác nước là cùng một chế độ xem như khả năng quan sát LLM truyền thống nhưng giờ được liên kết trực tiếp từ tổng quan đường ống qua mảng llmRunIds được lưu trong giai đoạn tác nhân AI, hỗ trợ nhiều lời gọi LLM mỗi lần chạy đường ống.

Tìm Kiếm & Lọc

Tìm kiếm — lọc span theo tên, loại hoặc thẻ
Lọc theo loại — chỉ hiển thị lời gọi LLM, lời gọi công cụ, chuỗi, v.v.
Sắp xếp — theo thời gian bắt đầu, thời lượng, tên hoặc loại
Bảng thống kê — số liệu tổng hợp: tổng số span, thời lượng trung bình/tối đa/tối thiểu, tỷ lệ thành công, phân tích theo loại

Xuất

Xuất toàn bộ dấu vết dưới dạng JSON, CSV hoặc sao chép tất cả span vào clipboard để gỡ lỗi hoặc phân tích bên ngoài.

Khi Có Sự Cố

Giai Đoạn Thất Bại

Nếu một giai đoạn thất bại (trạng thái = đỏ), thông báo lỗi được ghi lại và hiển thị trong thẻ giai đoạn. Đường ống vẫn tiếp tục — một chỉ thị bộ định tuyến thất bại không chặn các chỉ thị khác. Trạng thái tổng thể của lần chạy phản ánh liệu toàn bộ lần chạy thành công hay thất bại.

Short-Circuit AI

Khi một chỉ thị bộ định tuyến trả về short_circuit, giai đoạn tác nhân AI bị bỏ qua hoàn toàn. Tổng quan đường ống hiển thị huy hiệu cảnh báo trên giai đoạn bộ định tuyến và giai đoạn tác nhân AI hiển thị trạng thái “đã bỏ qua” mà không có dữ liệu. Đây là hành vi mong đợi — bộ định tuyến đã cố tình bỏ qua AI cho tin nhắn đó.

Thiếu Bản Ghi Lần Chạy

Nếu modal khả năng quan sát hiển thị “Không có dữ liệu đường ống” nhưng dấu vết thác nước tồn tại, lần chạy có thể đã bắt đầu trước khi tính năng khả năng quan sát được bật, hoặc tin nhắn được xử lý bởi một phiên bản trợ lý cũ hơn. Việc ghi lại đường ống được giới thiệu cùng với tính năng Khả Năng Quan Sát Trợ Lý Bán Hàng — các tin nhắn hiện có sẽ không có bản ghi lần chạy.

Kiến Trúc Kỹ Thuật

Mô Hình Dữ Liệu

Bản ghi lần chạy được lưu trữ trong một bộ sưu tập MongoDB riêng sales-assistant-runs (độc lập với bản ghi dấu vết LLM). Mỗi bản ghi chứa:

{
  runId: string,           // UUID — tương quan với dấu vết LLM
  status: string,          // "completed" | "failed"
  totalDurationMs: number,
  customerMessage: string,
  channelType: string,
  phases: {
    orderExtraction?: { ... },
    deterministicRouter?: {
      status: string,
      startTime: number,
      endTime: number,
      durationMs: number,
      instructionResults: [{
        instructionId: string,
        instructionContent: string,
        category: string,
        generatedCode: string,
        actions: [{ type, ... }],
        durationMs: number,
        success: boolean,
        error?: string
      }],
      shortCircuited: boolean,
      totalActionsProduced: number
    },
    aiAgent?: {
      status: string,
      modelUsed: string,
      tokenUsage: { prompt, completion, total },
      responsePreview: string,
      llmRunIds: string[],  // tham chiếu chéo đến dấu vết LLM
      handoverOccurred: boolean
    },
    deterministicCallback?: { ... },
    afterRun?: {
      attachmentsSent: [{ instructionId, attachmentId, success }],
      stateChanges: [{ key, from, to }],
      handoverOccurred: boolean,
      handoverReason?: string
    }
  },
  createdAt: string,
  completedAt?: string
}

Đường Ống Ghi Lại

Dịch vụ ghi lại bao bọc từng giai đoạn với thời gian, ghi nhận trạng thái và xử lý lỗi:

Bắt đầu giai đoạn — ghi lại thời gian bắt đầu và siêu dữ liệu giai đoạn
Thực thi giai đoạn — chạy logic thực tế (hàm bộ định tuyến, lời gọi AI, callback)
Kết thúc giai đoạn — ghi lại thời gian kết thúc, thời lượng, trạng thái và dữ liệu kết quả
Xử lý lỗi — nếu một giai đoạn ném lỗi, lỗi được ghi lại trong bản ghi giai đoạn và lần chạy tiếp tục

Trình ghi không bao giờ ném lỗi — lỗi luôn được ghi lại trong trạng thái giai đoạn để các giai đoạn hạ nguồn vẫn có thể thực thi.

Tương Quan

_id của lần chạy đường ống là khóa tương quan trên toàn bộ hệ thống:

Bản ghi lần chạy Trợ Lý Bán Hàng (các giai đoạn đường ống) —— _id
        ↓
Lần chạy Khả Năng Quan Sát LLM —— assistantPipelineRunId
        ↓
Cây lần chạy LangChain —— child_runs (đệ quy)

Mảng llmRunIds trong giai đoạn tác nhân AI liên kết trực tiếp đến các lần chạy khả năng quan sát LLM, cho phép bạn nhảy từ “AI đã nói điều này” đến “đây là mọi lời gọi LLM, lời gọi công cụ và bước chuỗi đã tạo ra nó.”

Thực Hành Tốt Nhất

Gỡ Lỗi Chỉ Thị Bộ Định Tuyến

Khi một chỉ thị bộ định tuyến không hoạt động như mong đợi, hãy mở tổng quan đường ống:

Kiểm tra giai đoạn Bộ Định Tuyến — chỉ thị có chạy không? (dấu xanh) Hay thất bại? (dấu đỏ)
Mở rộng chỉ thị để xem mã đã tạo — có khớp với ý định của bạn không?
Kiểm tra Các Hành Động Đã Trả Về — hàm thực tế đã tạo ra gì?
Nếu mã được tạo sai, hãy viết lại chỉ thị bằng ngôn ngữ rõ ràng hơn và xây dựng lại trợ lý

Kiểm Toán Hành Vi AI

Khi phản hồi AI có vẻ không đúng:

Mở Tổng Quan Đường Ống — kiểm tra các prompt có điều kiện nào đã được kích hoạt
Chuyển sang Dấu Vết LLM Dạng Thác Nước — mở rộng các span LLM để xem chính xác những gì đã gửi đến mô hình
Kiểm tra đầu vào và đầu ra của lời gọi công cụ — AI có gọi đúng công cụ với đối số chính xác không?

Giám Sát Hiệu Suất

Bảng thống kê trong dấu vết thác nước hiển thị các số liệu tổng hợp. Sử dụng nó để:

Xác định các lời gọi LLM hoặc lời gọi công cụ chậm
Theo dõi xu hướng sử dụng token
Theo dõi tỷ lệ thành công/thất bại theo thời gian

Tham Chiếu Chéo

Bản ghi lần chạy bao gồm cả tin nhắn khách hàng và bản xem trước phản hồi AI. Kết hợp với các thay đổi trạng thái trong hiệu ứng sau xử lý, bạn có thể tái tạo bối cảnh hội thoại đầy đủ cho bất kỳ tương tác tự động nào — hữu ích cho kiểm toán tuân thủ và giải quyết tranh chấp khách hàng.