Tool Definition Checker — Kiểm tra định nghĩa tool và hàm cho OpenAI, Anthropic, Gemini

Cùng một công cụ trong mỗi API

Cả ba API đều mô tả một công cụ bằng tên, phần mô tả và một JSON Schema cho các đối số, nhưng các trường nằm ở những vị trí khác nhau.

Tên có dấu chấm hoặc dấu hai chấm chỉ hợp lệ với Gemini. Trong tài liệu tham chiếu của OpenAI, nếu bỏ parameters thì hàm được định nghĩa với danh sách tham số rỗng, và một yêu cầu Chat Completions hỗ trợ tối đa 128 hàm trong tools.

Chế độ strict của OpenAI

• Các yêu cầu Chat Completions mặc định không ở chế độ strict. Các yêu cầu Responses sẽ cố chuyển schema của bạn sang chế độ strict khi có thể, và tài liệu tham chiếu Responses mô tả strict có giá trị mặc định là true.
• Ở chế độ strict, additionalProperties phải là false cho mọi đối tượng trong parameters, và mọi trường trong properties phải nằm trong required.
• Để một trường là tùy chọn ở chế độ strict, hãy thêm null vào các kiểu được phép, ví dụ type là ["string", "null"].
• Một schema vi phạm các quy tắc này sẽ bị từ chối, kèm chi tiết về các ràng buộc còn thiếu.
• Khi strict là true, chỉ một tập con của JSON Schema được hỗ trợ. Tài liệu Structured Outputs liệt kê tập con đó.

Các thuộc tính tùy chọn của công cụ Anthropic

• Mỗi ví dụ đầu vào phải hợp lệ theo input_schema của công cụ. Một ví dụ không hợp lệ sẽ trả về lỗi 400.
• Các ví dụ làm tăng số token của prompt: khoảng 20 đến 50 token cho một ví dụ đơn giản và khoảng 100 đến 200 cho một đối tượng lồng nhau phức tạp.
• input_examples không dùng được trên các công cụ phía máy chủ như web search hay code execution.

Các khai báo của Gemini

• Danh sách functionDeclarations của một công cụ chứa các khai báo hàm. Mô hình không chạy chúng. Nó có thể trả về một lệnh gọi hàm để mã của bạn thực thi.
• Một khai báo cần có name và description. Phần description được đánh dấu là bắt buộc.
• parameters, theo lược đồ OpenAPI, và parametersJsonSchema, nhận JSON Schema, loại trừ lẫn nhau. response và responseJsonSchema cũng loại trừ lẫn nhau theo cách tương tự.
• parametersJsonSchema phải mô tả một đối tượng mà các properties của nó là các tham số của hàm.
• Chế độ gọi hàm mặc định là AUTO. ANY luôn dự đoán một lệnh gọi hàm, NONE không dự đoán lệnh nào, còn VALIDATED để mô hình tự chọn nhưng kiểm tra lệnh gọi hàm bằng constrained decoding.
• allowedFunctionNames chỉ nên được đặt khi chế độ là ANY hoặc VALIDATED, và các tên phải khớp với tên của các khai báo.

Viết định nghĩa để mô hình dùng tốt

• Anthropic gọi phần mô tả chi tiết là yếu tố quan trọng nhất cho đến nay, và khuyên dùng ít nhất 3 đến 4 câu cho mỗi công cụ: nó làm gì, khi nào nên và không nên dùng, mỗi tham số có nghĩa gì, và những lưu ý nếu có.
• Anthropic khuyên gom các thao tác liên quan vào ít công cụ hơn bằng một tham số action, và thêm tiền tố tên dịch vụ vào tên, ví dụ github_list_prs.
• Anthropic cảnh báo rằng một tham số yêu cầu mô hình đưa ra lập luận của nó có thể dẫn đến việc từ chối, và gợi ý nên yêu cầu một lời giải thích ngắn thay thế.
• OpenAI khuyên nên mô tả rõ ràng mục đích của hàm và của từng tham số, dùng enum, và nhắm tới dưới 20 hàm ở đầu một lượt, điều mà OpenAI gọi là một gợi ý mềm.
• OpenAI lưu ý rằng các định nghĩa hàm có thể gọi được tính vào giới hạn ngữ cảnh và được tính phí như token đầu vào.