Hướng dẫn cốt lõi
Nhật ký và khắc phục sự cố
Lưu giữ các ID cần thiết để truy vết yêu cầu, tác vụ và chi phí
Hãy lưu giữ các ID yêu cầu, tác vụ và thanh toán của TokenLab trong nhật ký của bạn. Chúng kết nối hành động của người dùng với kết quả và chi phí tương ứng mà không cần lưu trữ prompt hoặc nội dung đa phương tiện riêng tư.
Trong Console, các chi tiết yêu cầu và phản hồi được ghi lại sẽ khả dụng trong 30 ngày kể từ thời điểm ghi, quyền truy cập sẽ kết thúc chính xác tại thời điểm hết hạn ngay cả khi quá trình dọn dẹp vật lý vẫn đang trong hàng đợi. Danh tính yêu cầu và lịch sử thanh toán/sử dụng có thời gian lưu trữ độc lập. Xem Lưu giữ dữ liệu.
Từ một yêu cầu đến điều tra và hỗ trợ
-
Mở Runs trong workspace sở hữu yêu cầu đó. Tìm Request ID của nó và chọn dòng tương ứng.
-
Chọn Open full details để xem trang chi tiết. Back to requests sẽ khôi phục các bộ lọc danh sách. Một liên kết không bao giờ cấp quyền truy cập vào một workspace khác; hãy sử dụng tài khoản được ủy quyền cho workspace đó.
-
Đối với trạng thái đang chờ xử lý hoặc không xác định, trước tiên hãy làm mới tiến trình. Đối với phản hồi thất bại hoặc bị gián đoạn, hãy chọn Investigate the issue khi có sẵn. Thao tác này sẽ bắt đầu một cuộc điều tra cho yêu cầu đó trong Agent trong ứng dụng; nó không phát lại yêu cầu mô hình gốc. Các yêu cầu thành công không cần điều tra theo mặc định.
-
Nếu bạn vẫn cần trợ giúp, hãy chọn hành động hỗ trợ từ con người (human-support) từ yêu cầu hoặc cuộc điều tra. Nó sẽ mở một bản xem trước với yêu cầu và cuộc hội thoại được liên kết khi có sẵn. Xem lại bản tóm tắt và xóa nội dung riêng tư, sau đó chọn Submit. Chỉ riêng một cuộc điều tra hoặc bản xem trước sẽ không gửi yêu cầu hỗ trợ.
-
Sau khi gửi, hãy giữ lại xác nhận và tiếp tục cuộc hội thoại đó trong Support. Hãy sử dụng lại nó cho các phản hồi và thông tin bổ sung thay vì gửi các yêu cầu trùng lặp.
Các ID cần lưu giữ
| Định danh | Nơi xuất hiện | Sử dụng cho |
|---|---|---|
request_id | Nội dung lỗi, nhật ký dashboard, bản ghi sử dụng | Hỗ trợ cấp yêu cầu và đối soát |
id / task_id | Phản hồi tạo và trạng thái bất đồng bộ (async) | Thăm dò (polling) bất kỳ tác vụ bất đồng bộ nào với GET /v1/tasks/{id} |
poll_url | Phản hồi tạo bất đồng bộ | URL trạng thái; thăm dò /v1/tasks/{id} với id |
billing_transaction_id | Phản hồi không truyền phát (non-streaming) khi đã thanh toán, phản hồi trạng thái tác vụ bất đồng bộ, bản ghi sử dụng, X-Billing-Transaction-ID | Đối soát chi phí |
X-Task-ID | Tiêu đề phản hồi tác vụ bất đồng bộ | Tương quan tác vụ cấp tiêu đề |
| ID công việc/người dùng của riêng bạn | Ứng dụng của bạn | Tìm yêu cầu TokenLab cho một hành động của người dùng |
Các bản ghi dành cho khách hàng nên sử dụng ID của TokenLab. Không bao giờ tiết lộ URL dịch vụ riêng tư, khóa bộ nhớ đệm hoặc siêu dữ liệu chẩn đoán.
Những gì cần ghi nhật ký
Ghi lại đủ thông tin để chẩn đoán yêu cầu mà không làm rò rỉ thông tin bảo mật:
- Endpoint, phương thức HTTP, mô hình, mã trạng thái, dấu thời gian và độ trễ.
- Các định danh công khai:
request_id,task_id,poll_urlvàbilling_transaction_idkhi có. - Tên các trường được gửi trong yêu cầu, không phải toàn bộ prompt hoặc nội dung đa phương tiện riêng tư.
- Các phản hồi trạng thái bất đồng bộ cuối cùng và các trường lỗi an toàn.
- Số lần thử lại của client và liệu việc thử lại có tạo ra tác vụ mới hay tiếp tục tác vụ hiện có.
Luôn ẩn (redact) Authorization, API key, token quản lý, URL đã ký, URL đa phương tiện riêng tư, toàn bộ prompt và dữ liệu cá nhân của người dùng trừ khi bạn có sự cho phép rõ ràng để lưu giữ chúng.
Ma trận khắc phục sự cố
| Triệu chứng | Kiểm tra đầu tiên | Trang hữu ích |
|---|---|---|
401 hoặc 403 | API key, token quản lý, quyền truy cập tổ chức, phạm vi khóa | Xác thực |
402 | Số dư, giới hạn chi tiêu API key | Thanh toán & Định giá |
429 | Gói tài khoản, giới hạn tốc độ endpoint, hành vi thử lại | Giới hạn tốc độ |
400 invalid_request_error | Trường không được hỗ trợ, sai endpoint, thiếu trường bắt buộc hoặc không khớp yêu cầu mô hình | Xử lý lỗi |
| Không tìm thấy tác vụ bất đồng bộ | Sai API key, sai ID hoặc tác vụ đã hết hạn | Công việc bất đồng bộ & Thăm dò |
| Chi phí không khớp với UI | Thời điểm thanh toán hoặc so sánh sai định danh | Thanh toán & Định giá |
Đối soát sử dụng
Sử dụng Management API để đối soát phía máy chủ:
curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video" \
-H "Authorization: Bearer mt-your-management-token"GET /v1/management/api-keys/{keyId}/usage có thể lọc theo scene, model, modelVendor, startDate và endDate. Hãy sử dụng các bản ghi này thay vì cào dữ liệu từ các trang Console hoặc tính toán chi phí chỉ từ số lượng token phản hồi. endDate chỉ có ngày nghĩa là 00:00 UTC vào đầu ngày đó; xem Nhận mức sử dụng API Key.
Các phản hồi truyền phát (streaming) có thể được thanh toán sau khi luồng được gửi, vì vậy tiêu đề thanh toán có thể vắng mặt ngay cả khi mức sử dụng được ghi lại sau đó. Các tác vụ đa phương tiện bất đồng bộ có thể được thanh toán sau khi thăm dò trạng thái cuối cùng.
Những gì cần gửi cho bộ phận hỗ trợ
Khi liên hệ với bộ phận hỗ trợ, hãy bao gồm:
request_id.task_idvàpoll_urlcho công việc bất đồng bộ.billing_transaction_idkhi có.- Endpoint, phương thức, mô hình, dấu thời gian và mã trạng thái.
- Tên các trường yêu cầu và nội dung lỗi an toàn.
- Kết quả mong đợi của bạn và những gì người dùng thực sự thấy.
Không bao gồm API key, token quản lý, đa phương tiện riêng tư, toàn bộ prompt, URL dịch vụ riêng tư hoặc các định danh chẩn đoán. Nếu bộ phận hỗ trợ cần một ví dụ về yêu cầu, hãy gửi một bản sao đã được ẩn thông tin nhạy cảm.
Các kiểm tra đáng tự động hóa
- Cảnh báo về các phản hồi
401,402,429và5xxlặp lại một cách riêng biệt; mỗi loại cần một phản hồi khác nhau. - Theo dõi các công việc bất đồng bộ vẫn ở trạng thái chưa kết thúc lâu hơn SLA sản phẩm của bạn.
- Theo dõi các nỗ lực tạo trùng lặp cho cùng một ID công việc của người dùng.
- Lấy mẫu các công việc đã hoàn thành và xác minh rằng tài sản hiển thị cho người dùng, bản ghi sử dụng và bản ghi tác vụ được lưu trữ khớp nhau.
Tài liệu tham khảo API
| Chủ đề | Tham khảo |
|---|---|
| Xử lý lỗi | Xử lý lỗi |
| Giới hạn tốc độ | Giới hạn tốc độ |
| Thanh toán & Định giá | Thanh toán & Định giá |
| Nhận mức sử dụng API Key | Nhận mức sử dụng API Key |
| Nhận trạng thái tác vụ | Nhận trạng thái tác vụ |