วิธีใช้ OpenAI Batch API

เมื่ออ่านคู่มือนี้จบ คุณจะสามารถเรียกใช้ OpenAI Batch API เพื่อรันคำขอโมเดลนับพันรายการเป็นงานอะซิงโครนัสเดียว และดึงผลลัพธ์ทั้งหมดกลับมาในราคาลด 50% คุณจะจัดแพ็กพร้อมท์ของคุณลงในไฟล์ JSONL ส่งแบทช์หนึ่งรายการ ตรวจสอบสถานะจนกว่าจะเสร็จสิ้น และดาวน์โหลดผลลัพธ์ จากนั้นทดสอบแต่ละขั้นตอนใน Apidog ก่อนที่จะนำไปใช้จริงในการผลิต หากงานของคุณมีการโต้ตอบมากกว่า เส้นทางแบบซิงโครนัสจะเหมาะสมกว่า และคุณสามารถ ทดสอบ ChatGPT API ด้วย Apidog แทนได้

Batch API คืออะไร และควรใช้เมื่อใด

Batch API คือ endpoint แบบอะซิงโครนัสสำหรับการเรียกใช้โมเดลจำนวนมากที่ยอมรับการหน่วงเวลาได้ แทนที่จะส่งคำขอ HTTP หนึ่งครั้งต่อพร้อมท์ คุณสามารถจัดแพ็กคำขอจำนวนมากลงในไฟล์ JSONL เดียว ส่งเป็นงานเดียว และตรวจสอบสถานะจนกว่าจะเสร็จสิ้น OpenAI จะรันงานในช่วงเวลาที่มีการใช้งานน้อย และส่งคืนผลลัพธ์ทั้งหมดในไฟล์เอาต์พุต

คุณจะได้รับประโยชน์ที่ชัดเจนสองประการ ประการแรกคือส่วนลด 50% สำหรับโทเค็นทั้งขาเข้าและขาออกเมื่อเทียบกับ synchronous API ประการที่สองคือปริมาณงานที่สูงขึ้น เนื่องจากงานแบทช์ใช้กลุ่มจำกัดอัตราที่แยกต่างหากและไม่แข่งขันกับการรับส่งข้อมูลแบบเรียลไทม์ของคุณ ข้อแลกเปลี่ยนคือความหน่วงเวลา OpenAI รับประกันว่าจะเสร็จสิ้นภายใน 24 ชั่วโมง แต่งานส่วนใหญ่จะเสร็จเร็วกว่านั้น แต่คุณไม่สามารถพึ่งพาสิ่งนั้นได้เสมอไป

ใช้การประมวลผลแบบแบทช์เมื่อเป็นงานออฟไลน์และมีปริมาณมาก:

การจัดหมวดหมู่หรือติดแท็กข้อมูลที่ค้างอยู่
การสร้าง embeddings สำหรับคลังข้อมูลทั้งหมด
การสร้างเนื้อหาจำนวนมาก (คำอธิบายผลิตภัณฑ์ สรุป การแปล)
การรันชุดการประเมินหรือการเปรียบเทียบโมเดลกับชุดข้อมูล

ข้ามวิธีนี้สำหรับสิ่งใดก็ตามที่ผู้ใช้กำลังรออยู่ ส่วนติดต่อผู้ใช้แชท การเติมข้อความอัตโนมัติ และตัวแทนสดต้องการ endpoints แบบซิงโครนัส หากคุณกำลังสร้างการกำหนดค่าโมเดลหรือตัวแทนจำนวนมากในคราวเดียว การประมวลผลแบบแบทช์จะเข้ากันได้ดีกับปริมาณงานดังกล่าว โปรดดูคำแนะนำของเราเกี่ยวกับการ สร้างการกำหนดค่าตัวแทนมากกว่า 100 รายการด้วยการประมวลผลแบบแบทช์

สิ่งที่คุณต้องมีก่อนเริ่มต้น

ขั้นตอนทั้งหมดครอบคลุมสอง endpoints คือ /v1/files และ /v1/batches และสี่ขั้นตอน นี่คือโครงสร้างก่อนที่เราจะดูการเรียกใช้

ขั้นตอน	Endpoint	สิ่งที่เกิดขึ้น
1. อัปโหลด	`POST /v1/files`	ส่งไฟล์ `.jsonl` ของคุณพร้อม `purpose: "batch"` และรับ file ID กลับมา
2. สร้าง	`POST /v1/batches`	ส่ง file ID พร้อม endpoint และ completion window
3. ตรวจสอบสถานะ	`GET /v1/batches/{id}`	ตรวจสอบ `status` จนกว่าจะแสดง `completed`
4. ดึงข้อมูล	`GET /v1/files/{id}/content`	ดาวน์โหลดผลลัพธ์ผ่าน `output_file_id`

ในการทำตาม คุณจะต้องมีคีย์ OpenAI API ที่ส่งออกเป็น OPENAI_API_KEY, ไฟล์ JSONL ของคำขอ และเครื่องมือสำหรับเรียกและตรวจสอบการเรียกใช้ แต่ละขั้นตอนจะส่งคืนวัตถุที่คุณสามารถยืนยันได้ ซึ่งทำให้วงจรชีวิตทั้งหมดง่ายต่อการทดสอบ

ขั้นตอนที่ 1: สร้างและอัปโหลดไฟล์ JSONL

ข้อมูลนำเข้าของคุณคือไฟล์ JSONL โดยแต่ละบรรทัดคือคำขอที่สมบูรณ์ในตัวเอง แต่ละบรรทัดต้องการสี่ฟิลด์: custom_id ที่คุณเลือก (เพื่อให้คุณสามารถจับคู่ผลลัพธ์กลับไปยังข้อมูลนำเข้าได้), method (POST), url (endpoint เป้าหมาย เช่น /v1/chat/completions) และ body ที่มีพารามิเตอร์คำขอจริง

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'shipping was slow but the product is great'"}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'returned it the same day'"}]}}

custom_id จะต้องไม่ซ้ำกันภายในไฟล์ ผลลัพธ์จะกลับมาโดยไม่มีลำดับที่รับประกัน ดังนั้น ID นั้นจึงเป็นวิธีที่คุณเชื่อมต่อการตอบกลับแต่ละรายการเข้ากับบรรทัดต้นฉบับ แบทช์เดียวสามารถรองรับคำขอได้สูงสุด 50,000 รายการ และไฟล์มีขนาดสูงสุด 200 MB

อัปโหลดไปยัง Files API โดยมี purpose เป็น batch:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@requests.jsonl"

การตอบกลับจะส่งคืน id ของไฟล์ (เช่น file-abc123) นั่นคือ input_file_id ของคุณสำหรับขั้นตอนต่อไป

ขั้นตอนที่ 2: สร้างแบทช์

ตอนนี้สร้างงาน คุณส่ง input_file_id, endpoint ที่คุณกำลังกำหนดเป้าหมาย และ completion_window ปัจจุบัน completion_window รับค่าเดียวคือ "24h"

curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": {"job": "sentiment-backfill"}
  }'

ฟิลด์ endpoint จะต้องตรงกับ url ที่ใช้ภายในบรรทัด JSONL ของคุณ เป้าหมายที่รองรับได้แก่ /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions และ /v1/moderations รวมถึงอื่นๆ ออบเจ็กต์ metadata ที่เป็นทางเลือกสามารถเก็บคู่ key-value ได้สูงสุด 16 คู่ ซึ่งมีประโยชน์สำหรับการแท็กงานที่คุณต้องการกรองในภายหลัง

การเรียกใช้จะส่งคืนออบเจ็กต์แบทช์ ฟิลด์ที่คุณจะสนใจมากที่สุด:

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "request_counts": { "total": 0, "completed": 0, "failed": 0 },
  "created_at": 1733452800,
  "metadata": { "job": "sentiment-backfill" }
}

ขั้นตอนที่ 3: ตรวจสอบสถานะแบทช์

แบทช์ใหม่จะเริ่มต้นที่สถานะ validating จากนั้นจะเคลื่อนผ่านชุดสถานะที่บันทึกไว้ ตรวจสอบสถานะโดยเรียก GET /v1/batches/{batch_id} และอ่านฟิลด์ status

สถานะ	ความหมาย
`validating`	กำลังตรวจสอบไฟล์ข้อมูลนำเข้าก่อนที่การรันจะเริ่มต้นขึ้น
`in_progress`	กำลังประมวลผลคำขอ
`finalizing`	การรันเสร็จสิ้นและกำลังเตรียมไฟล์เอาต์พุต
`completed`	เสร็จสิ้น; ผลลัพธ์พร้อมให้ดาวน์โหลด
`failed`	การตรวจสอบล้มเหลว; ไม่มีสิ่งใดรัน
`expired`	กรอบเวลา 24 ชั่วโมงปิดลงก่อนที่คำขอทั้งหมดจะเสร็จสิ้น
`cancelling` / `cancelled`	คุณร้องขอการยกเลิก

ออบเจ็กต์ request_counts (total, completed, failed) จะแสดงความคืบหน้าแบบเรียลไทม์ในขณะที่สถานะอยู่ที่ in_progress ไม่มี webhook ให้รอที่นี่ ดังนั้นการตรวจสอบสถานะเป็นระยะ (ทุกๆ สองสามนาที ไม่ใช่ทุกวินาที) จึงเป็นรูปแบบที่ถูกต้อง คุณยังสามารถยกเลิกงานที่กำลังรันได้ด้วย POST /v1/batches/{batch_id}/cancel หากคุณส่งงานไปโดยไม่ได้ตั้งใจ

ขั้นตอนที่ 4: ดึงผลลัพธ์

เมื่อ status แสดง completed ออบเจ็กต์แบทช์จะมี output_file_id ดาวน์โหลดเนื้อหาของไฟล์นั้นผ่าน Files API:

curl https://api.openai.com/v1/files/file-output456/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > results.jsonl

ผลลัพธ์จะอยู่ในรูปแบบ JSONL อีกครั้ง โดยมีหนึ่งบรรทัดต่อหนึ่งคำขอ แต่ละบรรทัดจะสะท้อน custom_id ที่คุณตั้งไว้ พร้อมด้วยออบเจ็กต์ response ที่มีรหัสสถานะและเนื้อหา คำขอใดๆ ที่เกิดข้อผิดพลาดจะปรากฏในไฟล์ที่อ้างอิงโดย error_file_id ดังนั้นควรตรวจสอบทั้งสองไฟล์ จับคู่ผลลัพธ์กับข้อมูลนำเข้าโดยใช้ custom_id ไม่ใช่ตามลำดับบรรทัด

ข้อควรพิจารณาเรื่องต้นทุนและกรอบเวลา

การคำนวณง่ายๆ คือ: คุณประหยัด 50% ของโทเค็น และยอมรับเวลาดำเนินการได้สูงสุด 24 ชั่วโมง สำหรับการ backfill ครั้งเดียวหรืองานที่รันทุกคืน นี่เป็นการตัดสินใจที่ง่ายดาย แต่สำหรับฟีเจอร์ในเส้นทางสำคัญของผลิตภัณฑ์ของคุณ สิ่งนี้ไม่เหมาะสม

ข้อควรทราบเชิงปฏิบัติบางประการ:

ส่วนลดใช้ได้กับโทเค็นทั้งขาเข้าและขาออก สำหรับโมเดลที่รองรับทั้งหมด
กรอบเวลา 24 ชั่วโมงเป็นเพดาน ไม่ใช่เป้าหมาย วางแผนสำหรับกรณีที่เลวร้ายที่สุด หากงานถึงสถานะ expired คำขอที่เสร็จสิ้นแล้วจะยังคงถูกเรียกเก็บเงินและส่งคืน ส่วนที่เหลือจะไม่ถูกดำเนินการ
งานแบทช์จะใช้ขีดจำกัดโทเค็นที่อยู่ในคิวแยกต่างหาก ดังนั้นแบทช์ขนาดใหญ่จะไม่ส่งผลกระทบต่อขีดจำกัดอัตราที่การรับส่งข้อมูลแบบเรียลไทม์ของคุณต้องพึ่งพา หากคุณกำลังประสบปัญหาเรื่องขีดจำกัด คู่มือของเราเกี่ยวกับ GPT API rate limits และวิธีการทดสอบ ครอบคลุมด้าน synchronous
โทเค็นครึ่งราคาจะยังคงเพิ่มขึ้นเมื่อปริมาณเพิ่มขึ้น ติดตามการใช้จ่ายต่องานโดยใช้แท็ก metadata เพื่อให้คุณสามารถระบุแหล่งที่มาของต้นทุนได้ในภายหลัง นี่คือ คู่มือการจัดสรรต้นทุนสำหรับการใช้จ่าย OpenAI

วิธีทดสอบใน Apidog

Batch API มีแนวโน้มที่จะเกิดข้อผิดพลาดมากกว่าการเรียกแชทเพียงครั้งเดียว เนื่องจากรูปแบบความล้มเหลวกระจายอยู่ทั่วไฟล์ การจัดรูปแบบ JSONL และวงจรการตรวจสอบสถานะ บรรทัดที่ผิดรูปแบบในไฟล์คำขอ 50,000 รายการอาจทำให้การอัปโหลดทั้งหมดล้มเหลว และคุณจะไม่รู้จนกว่าการตรวจสอบจะเสร็จสิ้น การทดสอบ endpoints วงจรชีวิตก่อนที่คุณจะทำให้เป็นอัตโนมัติจะช่วยประหยัดเวลาการทำงานซ้ำนั้น

Apidog เป็นแพลตฟอร์ม API ที่คุณสามารถรันแต่ละขั้นตอนเป็นคำขอ เชื่อมโยง และยืนยันการตอบกลับได้ โดยจะทดสอบและจำลอง endpoints ไม่ใช่ OpenAI SDK การตั้งค่าที่สมจริงมีลักษณะดังนี้:

ตรวจสอบรูปแบบ JSONL ก่อน. ก่อนที่คุณจะอัปโหลดสิ่งใดๆ ให้ยืนยันว่าแต่ละบรรทัดมี custom_id, method, url และ body และมี body.model และข้อความอยู่ การตรวจจับฟิลด์ที่ขาดหายไปในเครื่องถูกกว่าแบทช์ที่ล้มเหลว
รันการอัปโหลดแบบ multipart. ส่ง POST /v1/files ด้วย purpose=batch และไฟล์ของคุณ จากนั้นบันทึก id ที่ส่งคืนลงในตัวแปรสภาพแวดล้อม
สร้างแบทช์และยืนยันออบเจ็กต์. เรียก POST /v1/batches จากนั้นยืนยันว่า status คือ validating และ endpoint ตรงกับสิ่งที่คุณส่งไป การยืนยันด้วยภาพของ Apidog ช่วยให้คุณตรวจสอบฟิลด์เหล่านั้นได้โดยไม่ต้องเขียนสคริปต์
ตรวจสอบสถานะและดึงข้อมูล. เรียก GET /v1/batches/{id} ซ้ำๆ ยืนยันเมื่อ status กลายเป็น completed จากนั้นดึง output_file_id และดาวน์โหลดผลลัพธ์
ทดสอบเส้นทางยกเลิกและข้อผิดพลาด. ส่งไฟล์ที่ตั้งใจจะให้ผิดพลาดและยืนยันว่าคุณได้รับสถานะ failed และทดสอบ POST /v1/batches/{id}/cancel เพื่อให้การจัดการข้อผิดพลาดของคุณเป็นจริง ไม่ใช่เพียงการคาดเดา

เนื่องจากไฟล์เอาต์พุตจะมาถึงในภายหลัง คุณยังสามารถตั้งค่า mock API ที่ส่งคืนออบเจ็กต์แบทช์ที่เสร็จสมบูรณ์ตัวอย่างและไฟล์ผลลัพธ์ที่เตรียมไว้ ซึ่งช่วยให้คุณสร้างและทดสอบตรรกะการดึงข้อมูลและการแยกวิเคราะห์โดยไม่ต้องรอการทำงานจริง 24 ชั่วโมง และไม่ต้องเผาผลาญโทเค็นระหว่างการพัฒนา เมื่อทีมของคุณทำงานแบบ spec-first คุณยังสามารถ สร้างคอลเลกชันการทดสอบได้โดยตรงจาก OpenAPI spec และรักษา endpoints แบทช์ภายใต้การครอบคลุมของการถดถอยใน CI

คำถามที่พบบ่อย

แบทช์ใช้เวลานานเท่าไหร่จริง ๆ

OpenAI รับประกันว่าจะประมวลผลแบทช์ให้เสร็จภายใน 24 ชั่วโมง ในทางปฏิบัติ งานจำนวนมากจะเสร็จเร็วกว่านั้น แต่การรับประกันคือกรอบเวลาสูงสุด 24 ชั่วโมง ดังนั้นควรสร้างระบบของคุณโดยคำนึงถึงสิ่งนั้น หากกรอบเวลาปิดลงโดยที่งานยังไม่เสร็จสิ้น แบทช์จะเปลี่ยนเป็นสถานะ expired และเฉพาะคำขอที่เสร็จสมบูรณ์แล้วเท่านั้นที่จะถูกส่งคืนและเรียกเก็บเงิน

ส่วนลดจริงคือเท่าไหร่ และสามารถใช้ร่วมกับส่วนลดอื่นได้หรือไม่

Batch API มอบส่วนลด 50% แบบคงที่เมื่อเทียบกับ synchronous endpoints ทั้งโทเค็นขาเข้าและขาออก นี่เป็นตัวแปรต้นทุนที่ใหญ่ที่สุดที่ OpenAI เสนอสำหรับปริมาณงานแบบออฟไลน์ หากคุณพยายามจัดสรรการใช้จ่ายนั้นกลับไปยังฟีเจอร์หรืองานต่างๆ คู่มือการจัดสรรต้นทุน จะแสดงวิธีการแบ่งส่วน

ฉันสามารถรัน endpoints ใดได้บ้างในแบทช์

คุณตั้งค่าเป้าหมายในทั้ง url ของ JSONL และฟิลด์ endpoint ของแบทช์ และจะต้องตรงกัน เป้าหมายที่รองรับได้แก่ /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions และ /v1/moderations รวมถึง endpoints รูปภาพและวิดีโอ ตรวจสอบเอกสารปัจจุบันสำหรับรายการทั้งหมด เนื่องจาก OpenAI จะเพิ่มขึ้นเรื่อยๆ

ทำไมผลลัพธ์ของฉันถึงไม่อยู่ในลำดับ

ผลลัพธ์ไม่ได้เรียงลำดับ โดยการออกแบบ ไฟล์ JSONL เอาต์พุตไม่ได้รักษาลำดับบรรทัดของข้อมูลนำเข้า ซึ่งเป็นเหตุผลที่ทุกคำขอต้องมี custom_id ที่ไม่ซ้ำกัน จับคู่ผลลัพธ์กับข้อมูลนำเข้าโดยใช้ ID นั้น หากสองบรรทัดมี custom_id เดียวกัน คุณจะไม่สามารถแยกแยะการตอบกลับได้อย่างน่าเชื่อถือ

บทสรุป

ตอนนี้คุณมีขั้นตอนทั้งหมดแล้ว: จัดแพ็กพร้อมท์ของคุณลงในไฟล์ JSONL อัปโหลด สร้างแบทช์ ตรวจสอบสถานะ และดึงผลลัพธ์ ทั้งหมดนี้ในราคาโทเค็นครึ่งหนึ่งภายในกรอบเวลา 24 ชั่วโมง แต่ละขั้นตอนจะส่งคืนวัตถุที่คุณสามารถตรวจสอบได้ ดังนั้นเมื่อรูปแบบ JSONL และวงจรการตรวจสอบสถานะถูกต้อง ที่เหลือก็เป็นไปตามกลไก

ก่อนที่คุณจะทำให้เป็นอัตโนมัติ ให้รันวงจรชีวิตด้วยตนเอง ดาวน์โหลด Apidog เพื่อตรวจสอบไฟล์คำขอของคุณ ทดสอบ endpoints สำหรับการอัปโหลด การสร้าง การตรวจสอบสถานะ และการยกเลิก และยืนยันฟิลด์ออบเจ็กต์แบทช์ เพื่อให้บรรทัดที่ผิดรูปแบบไม่ทำให้คุณเสียเวลา 24 ชั่วโมง

ปุ่ม