Hướng dẫn gọi hàm cho API LLM Models dành cho Agent
Agent là một vòng lặp: mô hình chọn công cụ, mã của bạn thực thi nó, kết quả được trả lại và mô hình quyết định bước tiếp theo. Đây là phiên bản hoạt động của vòng lặp đó, kèm theo các giới hạn và chi phí bạn nên tính đến.

Điểm chính
- Endpoint hỗ trợ công cụ, tool_choice, tool_calls dạng streaming và kết quả công cụ theo vai trò.
- Giới hạn vòng lặp của bạn, xác thực đối số công cụ và thử lại các phản hồi 429 với thời gian chờ ngắn.
- Giữ số lượng worker đồng thời ở mức 8 trở xuống cho khóa đầy đủ; các luồng truyền phát giữ vị trí của chúng cho đến khi kết thúc.
- Một lần chạy agent gồm sáu bước với ngữ cảnh tăng dần tốn khoảng nửa xu.
Những gì agent cần từ API
Nếu bạn đang chọn API LLM models dành cho agent, danh sách kiểm tra ngắn hơn những gì marketing gợi ý. Bạn cần gọi hàm đáng tin cậy, cửa sổ ngữ cảnh đủ lớn để chứa nhật ký chạy, giới hạn tốc độ dự đoán và giá không phạt vòng lặp thực hiện nhiều yêu cầu.
API này bao gồm các điểm đó thông qua giao diện OpenAI tiêu chuẩn. Nó hỗ trợ tools và tool_choice, trả về tool_calls trong cả phản hồi bình thường và streaming, và chấp nhận kết quả công cụ dưới dạng tin nhắn với role: "tool". Chế độ JSON có sẵn thông qua response_format. Cửa sổ ngữ cảnh là 100.000 token cho prompt cộng với kết quả hoàn thành, và ID mô hình là uncensored.
Vì phía framework chỉ là client OpenAI, hầu hết các thư viện agent cho phép bạn đặt base URL đều hoạt động. Bạn trỏ chúng vào https://api.llmmodelsapi.com/v1, cung cấp khóa của bạn và đặt tên mô hình. Chi tiết cài đặt có trong tài liệu, và bạn có thể lấy khóa từ trang khóa.
Hai giới hạn định hình thiết kế. Thứ nhất, mô hình chỉ xử lý văn bản, nên mọi xử lý hình ảnh, âm thanh hoặc tệp phải diễn ra trong các công cụ của bạn và trả về dưới dạng văn bản. Thứ hai, không có embeddings trên endpoint này, nên nếu agent của bạn thực hiện truy xuất, tìm kiếm vector cần một nguồn khác.
Prompt hệ thống giữ vòng lặp ổn định
Hầu hết các lỗi agent đến từ hướng dẫn mơ hồ, không phải từ API. Một prompt hệ thống tốt cho mô hình biết nó là ai, các công cụ nào tồn tại, khi nào dừng và định dạng câu trả lời cuối cùng là gì. Dưới đây là một mẫu cho trợ lý nghiên cứu.
Bạn là trợ lý nghiên cứu. Bạn có thể gọi các công cụ search_notes và read_note. Chỉ gọi công cụ khi bạn cần thông tin mà mình chưa có. Sử dụng tối đa năm lệnh gọi công cụ. Khi bạn có đủ thông tin, hãy trả lời bằng một câu trả lời ngắn và liệt kê các ID ghi chú bạn đã sử dụng. Nếu các ghi chú không chứa câu trả lời, hãy nói rõ điều đó.
Hãy chú ý những gì nó làm. Nó đặt tên các công cụ, đặt ngân sách gọi, xác định điều kiện dừng và cấp quyền cho mô hình nói rằng nó không biết. Phần cuối cùng này rất quan trọng, vì một agent bị buộc phải trả lời sẽ bịa ra thứ gì đó.
Đặt nhiệt độ thấp cho việc sử dụng công cụ. Các giá trị khoảng 0,2 đến 0,4 giúp tên công cụ và định dạng đối số ổn định. Nếu agent của bạn cũng viết văn bản sáng tạo ở cuối, bạn có thể tăng nhiệt độ chỉ cho cuộc gọi cuối cùng đó. Tham số seed được chuyển tiếp, giúp bạn tái tạo một lần chạy khi gỡ lỗi.
Đối với các agent tiểu thuyết người lớn và nhập vai, cùng mẫu đó hoạt động: đặt nhân vật, quy tắc cảnh và các công cụ trong tin nhắn hệ thống. Mô hình được tinh chỉnh để trả lời mà không từ chối nội dung cho mục đích người lớn hợp pháp. Nội dung tình dục liên quan đến người chưa thành niên vẫn bị cấm.
Vòng lặp agent tối giản bằng Python
Vòng lặp bên dưới có một công cụ, một phép tra cứu trong từ điển đại diện cho dữ liệu thực của bạn. Nó dừng lại khi mô hình trả lời mà không có lệnh gọi công cụ, hoặc sau một số bước cố định.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY")
NOTES = {
"n1": "Invoice 114 was paid on March 3.",
"n2": "Invoice 115 is overdue by 12 days.",
}
def search_notes(query):
return [{"id": k, "text": v} for k, v in NOTES.items() if query.lower() in v.lower()]
TOOLS = [{
"type": "function",
"function": {
"name": "search_notes",
"description": "Search internal notes by keyword",
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
},
}]
SYSTEM = "You are a research assistant. Use search_notes when needed, at most five calls. Then answer briefly."
def run(question, max_steps=6):
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": question},
]
for step in range(max_steps):
resp = client.chat.completions.create(
model="uncensored",
messages=messages,
tools=TOOLS,
temperature=0.3,
max_tokens=500,
)
msg = resp.choices[0].message
messages.append(msg)
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
try:
args = json.loads(call.function.arguments)
result = search_notes(args["query"])
except Exception as exc:
result = {"error": str(exc)}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
return "Stopped: step limit reached."
print(run("Which invoice is overdue?"))
Ba chi tiết đáng chú ý. Giới hạn bước ngăn mô hình bị nhầm lẫn lặp lại cho đến khi hết ngân sách của bạn. Khối try chuyển đổi chuỗi đối số công cụ bị lỗi cú pháp thành thông báo lỗi mà mô hình có thể đọc và sửa. Và mọi kết quả công cụ đều được gửi lại với tool_call_id tương ứng, đây là cách mô hình biết mỗi câu trả lời thuộc về cuộc gọi nào.
Xử lý phản hồi 429 và độ đồng thời
Agent có tính bùng nổ. Một bộ lập kế hoạch có thể phân tán năm tác vụ con cùng lúc, và mỗi tác vụ chạy vòng lặp riêng của nó. Đó là nơi giới hạn tốc độ xuất hiện.
Một khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 yêu cầu mỗi phút. Một khóa dùng thử cho phép 2 và 60. Vượt quá giới hạn, API trả về HTTP 429. Mã lỗi cho bạn biết giới hạn nào bạn đã chạm: rate_limited cho yêu cầu mỗi phút, concurrency cho quá nhiều cùng lúc. Khi quá tải tạm thời, bạn cũng nhận được 429, với tiêu đề Retry-After: 5.
Hãy coi tất cả những trường hợp này có thể thử lại. Chờ số giây trong tiêu đề, hoặc vài giây nếu nó không có mặt, và gửi lại yêu cầu. Các yêu cầu thất bại không bị tính phí, nên các lần thử lại không tốn kém. Một lớp bao nhỏ sẽ thực hiện công việc.
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY", max_retries=0)
def chat_with_retry(**kwargs):
for attempt in range(5):
try:
return client.chat.completions.create(model="uncensored", **kwargs)
except RateLimitError as err:
wait = 5
if err.response is not None:
wait = int(err.response.headers.get("retry-after", 5))
time.sleep(wait)
raise RuntimeError("Still rate limited after 5 attempts")
Để tránh lỗi 429 ngay từ đầu, hãy giới hạn nhóm worker của bạn. Semaphore với giá trị 8 phù hợp với khóa đầy đủ. Nếu bạn truyền phát phản hồi đến giao diện người dùng, hãy nhớ rằng một luồng truyền phát giữ vị trí độ đồng thời của nó cho đến khi token cuối cùng đến, vì vậy một khách hàng chậm đọc câu trả lời dài sẽ chiếm vị trí đó trong suốt thời gian đó. Đọc các tiêu đề X-RateLimit-Limit-Requests và X-RateLimit-Limit-Concurrency cho phép mã của bạn thích ứng với khóa nào mà nó đang sử dụng.
Ngữ cảnh, bộ nhớ và chi phí cho một lần chạy
Mỗi bước của vòng lặp gửi lại toàn bộ lịch sử trò chuyện. Đó là cách các API chat hoạt động, và điều đó có nghĩa là token đầu vào tăng lên với mỗi cuộc gọi công cụ. Hãy xem xét một lần chạy sáu bước, trong đó prompt bắt đầu ở mức 2.000 token và tăng thêm 1.000 token mỗi bước, với 300 token đầu ra mỗi bước.
- Token đầu vào: 2.000 + 3.000 + 4.000 + 5.000 + 6.000 + 7.000 = 27.000
- Token đầu ra: 6 x 300 = 1.800
- Chi phí đầu vào: 27.000 x 0,15 / 1.000.000 = $0,00405
- Chi phí đầu ra: 1.800 x 0,50 / 1.000.000 = $0,0009
- Tổng cộng: $0,00495 cho mỗi lần chạy
Một nghìn lần chạy như vậy tốn $4,95. Điều đó đủ rẻ để cho phép agent suy nghĩ qua nhiều bước, nhưng sự gia tăng này cần được theo dõi. Với 100.000 token không gian, một agent chạy dài sẽ cuối cùng làm đầy cửa sổ, và một prompt lớn như vậy tốn 100.000 x 0,15 / 1.000.000 = $0,015 cho đầu vào trong mỗi bước.
Ba thói quen giữ nó dưới sự kiểm soát. Cắt ngắn các kết quả công cụ lớn trước khi đưa vào lịch sử trò chuyện, ví dụ như 2.000 ký tự đầu tiên của một trang web. Tóm tắt các bước cũ thành một tin nhắn ngắn khi lịch sử vượt quá ngưỡng. Và lưu trữ các sự kiện bền vững trong cơ sở dữ liệu của riêng bạn thay vì dựa vào cuộc trò chuyện làm bộ nhớ.
Tiêu đề X-Balance-USD trên mỗi phản hồi hiển thị tín dụng còn lại, vì vậy một giám sát agent có thể dừng một lần chạy khi số dư giảm xuống dưới mức sàn. Tín dụng là tín dụng trả trước từ $20 và không bao giờ hết hạn. Xem trang giá cả để biết về các khoản thưởng nạp tiền.
Các giới hạn thực tế để lập kế hoạch
Các agent được xây dựng trên bất kỳ mô hình nào đều cần hàng rào bảo vệ, và cái này cũng không ngoại lệ. Hãy sẵn sàng cho những điều sau đây.
- Đối số bị lỗi cú pháp. Mô hình có thể tạo ra các đối số công cụ không phải là JSON hợp lệ hoặc thiếu trường bắt buộc. Hãy phân tích một cách phòng thủ và trả về lỗi dưới dạng kết quả công cụ.
- Lựa chọn công cụ sai. Viết các mô tả công cụ ngắn gọn và khác biệt. Nếu hai công cụ nghe giống nhau, mô hình sẽ nhầm lẫn chúng. Sử dụng
tool_choiceđể bắt buộc gọi một công cụ cụ thể khi luồng yêu cầu một cuộc gọi. - Chỉ văn bản. Không có đầu vào hoặc đầu ra hình ảnh, không có âm thanh, không có embedding, không có tinh chỉnh. Hãy xử lý những phần đó ở nơi khác và truyền kết quả dưới dạng văn bản.
- Một mô hình đơn. Có một mô hình trọng số mở duy nhất đằng sau endpoint, không phải là trình định tuyến giữa các nhà cung cấp. Bạn không thể chọn một mô hình nhỏ hơn cho các bước dễ dàng.
- Công cụ phá hủy. Không cấp cho agent một công cụ xóa hoặc thanh toán mà không có bước xác nhận trong mã của riêng bạn.
Các agent lập kế hoạch cũng được hưởng lợi từ một lần chạy lại thứ hai. Sau khi vòng lặp trả về câu trả lời, bạn có thể thực hiện một cuộc gọi rẻ hơn nữa yêu cầu mô hình kiểm tra câu trả lời đối với các kết quả công cụ mà nó đã thấy, sử dụng chế độ JSON để trả về phán quyết và danh sách các tuyên bố không được hỗ trợ. Điều này thêm vài trăm token và bắt được lỗi phổ biến nhất, đó là một câu trả lời tự tin nhưng bỏ qua những gì các công cụ đã trả về.
Cuối cùng, hãy ghi lại mọi bước. Lưu các tin nhắn, các đối số công cụ và tiêu đề X-Request-Id từ mỗi phản hồi. Khi một lần chạy bị lỗi, ID yêu cầu cho phép bạn trỏ vào cuộc gọi chính xác, và lịch sử trò chuyện được ghi lại cho thấy kết quả công cụ nào đã làm mô hình hiểu lầm. Các agent dễ cải thiện nhất khi bạn có thể phát lại một lần chạy kém và thay đổi một thứ một lúc.
Hãy thử nghiệm một agent với tín dụng dùng thử miễn phí trước khi cam kết. Người dùng mới có thể nhận $0,50 tín dụng, đủ để chạy khoảng 101 vòng chạy đầy đủ ở ví dụ trên (0,50 / 0,00495). Hãy nhớ đến 2 yêu cầu đồng thời của tín dụng dùng thử và chỉ chạy một agent tại một thời điểm. Để tìm hiểu rộng hơn về dịch vụ, hãy đọc tổng quan theo token. Các prompt không được sử dụng để huấn luyện.
Hướng dẫn khác
Hỏi đáp
API có hỗ trợ gọi công cụ cho agent không?
Có. API chấp nhận công cụ và tool_choice, trả về tool_calls (kể cả khi truyền phát), và xử lý kết quả dưới dạng tin nhắn có role tool.
Có bao nhiêu cuộc gọi agent có thể chạy đồng thời?
Một khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 mỗi phút. Một khóa dùng thử cho phép 2 yêu cầu đồng thời và 60 mỗi phút.
Agent nên làm gì khi nhận được 429?
Chờ giá trị của tiêu đề Retry-After hoặc vài giây nếu không có, sau đó thử lại. Các yêu cầu bị từ chối không bị tính phí.
Agent có xử lý được hình ảnh hoặc âm thanh không?
Không. Mô hình chỉ xử lý văn bản, nên mọi phương tiện khác phải được xử lý bằng các công cụ của bạn và truyền vào dưới dạng văn bản.
Khóa của bạn chỉ cách một bước
Tạo tài khoản, sao chép khóa, thay đổi URL cơ sở. Đó là toàn bộ cài đặt.