tool_choice: auto, any, และ forced

แนวคิด

พารามิเตอร์ tool_choice ควบคุมว่าโมเดลจะเรียก tool หรือไม่ และเรียกตัวไหน มีสี่ค่า ค่าแรกคือ auto โมเดลตัดสินเองว่าจะเรียก tool ไหมในแต่ละเทิร์น เป็นค่าเริ่มต้นเมื่อมี tools ค่าที่สองคือ any โมเดลต้องเรียก tool สักตัว แต่เลือกเองว่าตัวไหน ค่าที่สามคือ forced เขียนเป็น {"type": "tool", "name": "..."} บังคับให้เรียก tool ที่ระบุเสมอ ค่าที่สี่คือ none ห้ามเรียก tool ใด ๆ เป็นค่าเริ่มต้นเมื่อไม่มี tools

จุดที่ต้องรู้คือ เมื่อ tool_choice เป็น any หรือ forced API จะ prefill ข้อความของ assistant เพื่อบังคับให้เกิด tool use แปลว่าโมเดลจะไม่พิมพ์ข้อความธรรมชาติหรือคำอธิบายก่อน tool_use block แม้เราจะสั่งให้อธิบาย ถ้าอยากได้ทั้งคำอธิบายและการเรียก tool เจาะจง ให้ใช้ auto แล้วสั่งใน user message แทน เช่น "ใช้ tool get_weather ในคำตอบ"

ทำไมสำคัญ

any มีประโยชน์เมื่อเรารับประกันว่าต้องมีการเรียก tool ไม่ใช่ข้อความสนทนา เช่น pipeline ที่ผลลัพธ์ต้องมาจาก tool เสมอ ส่วน forced มีประโยชน์เมื่อเราต้องการให้ tool ตัวใดตัวหนึ่งถูกเรียกก่อน exam guide ยกตัวอย่างการบังคับให้ extract_metadata ทำงานก่อน enrichment tool อื่น ๆ แล้วประมวลผลขั้นต่อไปในเทิร์นถัดไป รูปแบบนี้ทำให้ลำดับที่จำเป็นเกิดขึ้นแน่นอน แทนที่จะหวังให้โมเดลเลือกลำดับเอง

การบังคับ tool ตัวแรกด้วย forced ต่างจากการใช้ programmatic prerequisite ที่บล็อกการเรียกจนกว่าเงื่อนไขจะครบ tool_choice จัดการที่ระดับ "รอบนี้เรียกอะไร" ส่วน prerequisite จัดการที่ระดับ "ห้ามเรียกจนกว่า..." ทั้งสองเป็นกลไกคนละชั้น เลือกใช้ตามว่าต้องการควบคุมจุดไหน

มีข้อจำกัดที่ควรจำจากเอกสาร เมื่อใช้ extended thinking ร่วมกับ tool use ค่า any และ forced ไม่รองรับและจะ error รองรับเฉพาะ auto (ค่าเริ่มต้น) กับ none นอกจากนี้การเปลี่ยน tool_choice จะทำให้ cache ของ message block ใช้ไม่ได้ แม้ tool definition กับ system prompt จะยัง cache อยู่ก็ตาม

ตัวอย่าง

// auto — โมเดลตัดสินเอง (ค่าเริ่มต้นเมื่อมี tools)
{ "tool_choice": {"type": "auto"} }

// any — ต้องเรียก tool สักตัว แต่เลือกเอง
{ "tool_choice": {"type": "any"} }

// forced — บังคับ tool ตัวนี้ก่อน (เช่น extract_metadata ก่อน enrichment)
{ "tool_choice": {"type": "tool", "name": "extract_metadata"} }

// none — ห้ามเรียก tool
{ "tool_choice": {"type": "none"} }

เช็คความเข้าใจ

อ่านต่อ

• Define tools — forcing tool use
• Tool use overview