TokenLab

Hướng dẫn cốt lõi

Xây dựng tích hợp TokenLab đáng tin cậy

Kiểm soát chi phí, thử lại, khóa API và hồ sơ yêu cầu

Một tích hợp tốt sẽ hiển thị rõ ràng các lựa chọn về giá và mô hình, vượt qua được các lỗi mạng thông thường và không bao giờ để lộ khóa API trên trình duyệt. Các phương pháp dưới đây áp dụng cho các API chat, hình ảnh, video, âm thanh và các API khác của TokenLab.

Chọn các mô hình với dữ liệu hiện tại

Tên, khả năng và giá của các mô hình luôn thay đổi. Hãy đọc Models API hoặc các trang mô hình thay vì lưu giữ một danh sách cố định trong mã nguồn hoặc tài liệu.

Đối với một trường hợp sử dụng mới:

  1. Lọc các mô hình theo khả năng mà sản phẩm của bạn cần.
  2. So sánh giá TokenLab hiện tại của chúng.
  3. Kiểm thử một tập hợp nhỏ với các yêu cầu người dùng tiêu biểu.
  4. Giữ ID mô hình rõ ràng trong mỗi yêu cầu.

Đừng thay đổi mô hình một cách âm thầm. Việc thay thế có thể làm thay đổi chất lượng đầu ra, giá cả, độ dài ngữ cảnh, các công cụ khả dụng hoặc hỗ trợ phương tiện.

Đặt giới hạn chi phí

Đối với các mô hình văn bản, hãy giới hạn đầu ra ở độ dài mà sản phẩm của bạn thực sự có thể sử dụng. Tên tham số phụ thuộc vào API và mô hình, vì vậy hãy kiểm tra trang mô hình trước khi gửi max_tokens hoặc max_output_tokens.

Các hướng dẫn ngắn hơn không tự động tốt hơn, nhưng ngữ cảnh trùng lặp và các đoạn mã lặp đi lặp lại luôn làm tăng token đầu vào. Hãy giữ các hướng dẫn ổn định ở mức súc tích và chỉ gửi lịch sử cần thiết cho câu trả lời tiếp theo.

Đối với các yêu cầu về hình ảnh, video, âm nhạc, 3D và Worlds, chi phí thường phụ thuộc vào số lượng đầu ra, thời lượng, độ phân giải hoặc các tùy chọn phương tiện khác. Hãy hiển thị ước tính hiện tại trước khi người dùng xác nhận một quá trình tạo tốn kém bất cứ khi nào API có thể cung cấp.

Truyền phát (Stream) các phản hồi văn bản dài

Truyền phát giúp hiển thị câu trả lời ngay khi nó đến và tránh việc bắt người dùng phải chờ đợi phản hồi hoàn chỉnh. Nó không làm giảm chi phí token.

Để xem ví dụ đầy đủ về thiết lập máy khách và kiểm tra hoàn tất, hãy xem Streaming.

Xử lý việc ngắt kết nối như một câu trả lời chưa hoàn chỉnh. Không trình bày đầu ra một phần là đã hoàn thành thành công và không tự động lặp lại yêu cầu khi việc đó có thể tạo ra tác dụng phụ thứ hai hoặc tính phí.

Chỉ thử lại khi an toàn

Thử lại các phản hồi 429 sau khi nhận được Retry-After hoặc retry_after. Cơ chế chờ đợi theo cấp số nhân (exponential backoff) ngắn là phù hợp cho các phản hồi 5xx tạm thời. Các lỗi xác thực, xác thực dữ liệu, số dư và độ dài ngữ cảnh cần sự thay đổi từ ứng dụng hoặc người dùng; việc gửi lại cùng một yêu cầu sẽ không khắc phục được chúng.

Xem Giới hạn tốc độ (Rate limits) để biết ví dụ về thử lại có giới hạn, tuân thủ Retry-After và vô hiệu hóa các lần thử lại trùng lặp của SDK.

Đặt giới hạn thử lại và giới hạn thời gian tổng thể. Đối với việc tạo phương tiện, hãy lưu ID tác vụ được trả về. Đối với các yêu cầu được liệt kê trong Retry safely with an idempotency key, hãy gửi Idempotency-Key để việc thử lại sau khi hết thời gian chờ không thể chạy hoặc tính phí cùng một yêu cầu hai lần.

Giữ khóa API trên máy chủ

Không bao giờ nhúng khóa API TokenLab vào JavaScript của trình duyệt, gói ứng dụng di động, kho lưu trữ công khai hoặc nhật ký hiển thị cho máy khách.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

Sử dụng các khóa API riêng biệt cho môi trường phát triển, sản xuất và các ứng dụng độc lập. Chỉ cấp cho mỗi khóa các mô hình và giới hạn chi tiêu cần thiết. Thu hồi khóa ngay lập tức nếu nó có khả năng đã bị lộ.

Lưu giữ hồ sơ yêu cầu hữu ích

Lưu trữ các định danh cho phép bạn kết nối hành động của người dùng với hồ sơ sử dụng và hỗ trợ:

  • request_id cho yêu cầu API
  • task_id cho quá trình tạo bất đồng bộ
  • billing_transaction_id khi được trả về
  • ID mô hình và endpoint
  • ID người dùng, dự án hoặc công việc của riêng bạn

Không ghi nhật ký khóa API, token quản lý, các prompt riêng tư đầy đủ, phương tiện riêng tư hoặc các URL đã ký. Hồ sơ sử dụng trong Console và Management API là nguồn cho các khoản tiền được tính; chỉ riêng số lượng token phản hồi của mô hình có thể không mô tả chính xác khoản phí cuối cùng.

Thiết kế cho công việc bất đồng bộ

Các API hình ảnh, video, âm nhạc, 3D và Worlds có thể trả về trước khi kết quả sẵn sàng. Hãy lưu ID tác vụ, thăm dò GET /v1/tasks/{id} và chỉ dừng lại ở trạng thái completed hoặc failed. Việc tra cứu trạng thái thất bại không có nghĩa là bản thân quá trình tạo đã thất bại.

Xem Các tác vụ bất đồng bộ và polling để biết cách xử lý hủy bỏ, hết thời gian chờ và yêu cầu trùng lặp.

Trước khi ra mắt

  • Chạy các yêu cầu tiêu biểu với đúng mô hình và định dạng API mà bạn sẽ phát hành.
  • Kiểm tra cả phản hồi thành công và các phản hồi lỗi phổ biến.
  • Xác nhận giá hiển thị trong sản phẩm của bạn khớp với giá hiện tại của TokenLab.
  • Đảm bảo các thao tác làm mới, hết thời gian chờ mạng và nhấp chuột lặp lại được an toàn.
  • Đảm bảo có thể truy xuất kết quả hiển thị cho người dùng ngược lại Request ID của nó.

Trên trang này