Thanawat Wongchai

Posted on Jun 25 • Originally published at apidog.com

วิธีใช้ OpenAI Batch API

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

ลองใช้ Apidog วันนี้

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

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

เหมาะกับงาน offline ปริมาณมาก เช่น:

จัดหมวดหมู่หรือติดแท็กข้อมูลย้อนหลัง
สร้าง embeddings สำหรับ dataset ขนาดใหญ่
สร้างเนื้อหาจำนวนมาก เช่น product descriptions, summaries, translations
รัน evaluation suite หรือ benchmark โมเดลกับ dataset

ไม่เหมาะกับงานที่ผู้ใช้รอผลแบบ real-time เช่น chat UI, autocomplete หรือ live agents เพราะ Batch API รับประกันกรอบเวลาสูงสุด 24 ชั่วโมง ไม่ใช่การตอบกลับทันที

ถ้าคุณต้องสร้าง config หรือตัวแทนจำนวนมากพร้อมกัน การประมวลผลแบบ batch จะเหมาะกับ use case นี้ ดูตัวอย่างเพิ่มเติมได้ที่ สร้างการกำหนดค่าตัวแทนมากกว่า 100 รายการด้วยการประมวลผลแบบแบทช์

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

คุณจะใช้ 2 endpoints หลัก:

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

สิ่งที่ต้องเตรียม:

OpenAI API key ตั้งเป็น environment variable: OPENAI_API_KEY
ไฟล์ JSONL ที่มี request ต่อบรรทัด
เครื่องมือสำหรับยิง request และตรวจสอบ response เช่น curl หรือ Apidog

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

ไฟล์ input ต้องเป็น JSONL โดย 1 บรรทัด = 1 request ที่สมบูรณ์ แต่ละบรรทัดต้องมีฟิลด์หลัก:

custom_id: ID ที่คุณกำหนดเอง ต้องไม่ซ้ำภายในไฟล์
method: โดยทั่วไปคือ POST
url: endpoint เป้าหมาย เช่น /v1/chat/completions
body: request body จริงที่ส่งให้โมเดล

ตัวอย่าง requests.jsonl:

{"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'"}]}}

ผลลัพธ์ไม่ได้รับประกันลำดับเดียวกับ input ดังนั้นให้ใช้ custom_id เพื่อจับคู่ response กลับไปยัง request เดิมเสมอ

ข้อจำกัดสำคัญ:

1 batch รองรับได้สูงสุด 50,000 requests
ขนาดไฟล์สูงสุด 200 MB
custom_id ต้องไม่ซ้ำกัน

อัปโหลดไฟล์ไปยัง Files API โดยตั้ง purpose=batch:

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

response จะมี id ของไฟล์ เช่น:

{
  "id": "file-abc123",
  "object": "file",
  "purpose": "batch"
}

เก็บค่านี้ไว้เป็น input_file_id สำหรับขั้นตอนถัดไป

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

สร้าง batch job โดยส่ง:

input_file_id: file ID จากขั้นตอนก่อนหน้า
endpoint: endpoint ที่ตรงกับ url ใน JSONL
completion_window: ปัจจุบันใช้ "24h"
metadata: optional สำหรับติด tag งาน

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 เช่นถ้า JSONL ใช้ /v1/chat/completions batch ก็ต้องระบุ /v1/chat/completions

ตัวอย่าง response:

{
  "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"
  }
}

ฟิลด์ที่ควรเก็บไว้:

id: batch ID ใช้สำหรับ poll สถานะ
status: สถานะปัจจุบัน
output_file_id: ใช้ดาวน์โหลดผลลัพธ์เมื่อเสร็จ
error_file_id: ใช้ดู request ที่ error
request_counts: จำนวน request ทั้งหมด/สำเร็จ/ล้มเหลว

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

เรียก GET /v1/batches/{batch_id} เพื่อดูสถานะ:

curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY"

สถานะที่ควรรู้:

สถานะ	ความหมาย
`validating`	กำลังตรวจสอบไฟล์ input
`in_progress`	กำลังประมวลผล request
`finalizing`	ประมวลผลเสร็จและกำลังเตรียม output file
`completed`	เสร็จแล้ว ดาวน์โหลดผลลัพธ์ได้
`failed`	validation ล้มเหลว ไม่มี request ถูกประมวลผล
`expired`	ครบกรอบเวลา 24 ชั่วโมงก่อนประมวลผลครบ
`cancelling` / `cancelled`	กำลังยกเลิกหรือยกเลิกแล้ว

ระหว่าง in_progress ให้ดู progress จาก:

"request_counts": {
  "total": 50000,
  "completed": 30000,
  "failed": 12
}

ไม่มี webhook สำหรับรอผล ดังนั้นให้ poll เป็นระยะ เช่น ทุก 2–5 นาที ไม่ควร poll ทุกวินาที

ถ้าต้องการยกเลิกงาน:

curl -X POST https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY"

ขั้นตอนที่ 4: ดาวน์โหลดผลลัพธ์

เมื่อ status เป็น completed response ของ batch จะมี output_file_id

ดาวน์โหลดไฟล์ output:

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

ผลลัพธ์จะเป็น JSONL เช่นกัน โดย 1 บรรทัดต่อ 1 request และมี custom_id สำหรับจับคู่กับ input

ตัวอย่างโครงสร้างผลลัพธ์:

{
  "custom_id": "req-1",
  "response": {
    "status_code": 200,
    "body": {
      "id": "chatcmpl-...",
      "object": "chat.completion"
    }
  },
  "error": null
}

แนวทาง parse ผลลัพธ์:

อ่าน results.jsonl ทีละบรรทัด
parse เป็น JSON
ใช้ custom_id เพื่อ map กลับไปยัง record เดิม
ตรวจสอบ response.status_code
ถ้ามี error_file_id ให้ดาวน์โหลด error file เพิ่มเติม

ตัวอย่าง parse ด้วย Node.js:

import fs from "node:fs";
import readline from "node:readline";

const input = fs.createReadStream("results.jsonl");

const rl = readline.createInterface({
  input,
  crlfDelay: Infinity,
});

for await (const line of rl) {
  if (!line.trim()) continue;

  const item = JSON.parse(line);

  console.log({
    customId: item.custom_id,
    statusCode: item.response?.status_code,
    hasError: Boolean(item.error),
  });
}

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

Batch API เหมาะเมื่อคุณยอมรับ latency ได้สูงสุด 24 ชั่วโมงเพื่อแลกกับต้นทุน token ที่ลดลง 50%

ใช้ได้ดีกับ:

nightly jobs
backfill ข้อมูล
offline evaluation
batch embeddings
content generation จำนวนมาก

ไม่ควรใช้กับ:

request ที่ผู้ใช้รอหน้า UI
chatbot แบบ real-time
workflow ที่ต้องการผลลัพธ์ภายในไม่กี่วินาที

ข้อควรจำ:

ส่วนลด 50% ใช้กับโทเค็นขาเข้าและขาออกสำหรับโมเดลที่รองรับ
กรอบเวลา 24 ชั่วโมงคือเพดาน ไม่ใช่ SLA ว่าจะเสร็จเร็ว
ถ้า batch เป็น expired เฉพาะ request ที่ประมวลผลสำเร็จแล้วเท่านั้นที่จะถูกส่งคืนและถูกเรียกเก็บเงิน
batch jobs ใช้ rate limit pool แยกจาก synchronous traffic จึงไม่กระทบ real-time API limits ของคุณ
ควรใช้ metadata เพื่อติด tag งานและ track cost ภายหลัง

ถ้าคุณต้องจัดการ rate limit ฝั่ง synchronous ดูเพิ่มเติมที่ GPT API rate limits และวิธีการทดสอบ

ถ้าต้องการแยกต้นทุนตาม feature หรือ job ดู คู่มือการจัดสรรต้นทุนสำหรับการใช้จ่าย OpenAI

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

Batch API มีจุดที่พลาดได้หลายจุด เช่น JSONL format, multipart upload, batch lifecycle, polling, output parsing และ error handling การทดสอบ flow ก่อน automate จะช่วยลดเวลารอซ้ำเมื่อ batch ล้มเหลว

Apidog ช่วยให้คุณทดสอบแต่ละ endpoint, chain request และตรวจสอบ response ได้โดยไม่ต้องเขียนสคริปต์ทั้งหมดตั้งแต่แรก

ตั้งค่า flow ทดสอบแบบนี้:

ตรวจ JSONL ก่อนอัปโหลด

ตรวจว่าทุกบรรทัดมี custom_id, method, url, body, body.model และ payload ที่ถูกต้อง
ทดสอบ multipart upload

เรียก POST /v1/files พร้อม purpose=batch และแนบไฟล์ .jsonl จากนั้นบันทึก id ที่ได้เป็น environment variable เช่น input_file_id
สร้าง batch

เรียก POST /v1/batches โดยใช้ input_file_id แล้วตรวจว่า:
- status เป็น validating
- endpoint ตรงกับที่ส่ง
- input_file_id ถูกต้อง
poll สถานะ

เรียก GET /v1/batches/{id} ซ้ำเป็นระยะ และดู status, request_counts, output_file_id, error_file_id
ดาวน์โหลด output

เมื่อ completed ให้ใช้ output_file_id เรียก GET /v1/files/{id}/content
ทดสอบ error path

ส่ง JSONL ที่ตั้งใจให้ผิด เช่นขาด custom_id หรือ body เพื่อดู behavior ของ failed และทดสอบ POST /v1/batches/{id}/cancel

เนื่องจาก output file อาจมาช้า คุณสามารถใช้ mock API เพื่อจำลอง batch ที่เสร็จแล้ว และ mock ไฟล์ผลลัพธ์สำหรับทดสอบ parser โดยไม่ต้องรอ 24 ชั่วโมงหรือใช้ token จริง

ถ้าทีมทำงานแบบ spec-first คุณยังสามารถ สร้างคอลเลกชันการทดสอบได้โดยตรงจาก OpenAPI spec เพื่อให้ endpoints ของ batch อยู่ใน regression test ได้

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

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

OpenAI รับประกันกรอบเวลาสูงสุด 24 ชั่วโมง หลายงานอาจเสร็จเร็วกว่านั้น แต่ควรออกแบบระบบโดยสมมติ worst case ที่ 24 ชั่วโมง

ถ้าไม่เสร็จภายในกรอบเวลา batch จะเป็น expired และเฉพาะ request ที่ประมวลผลสำเร็จแล้วเท่านั้นที่จะถูกส่งคืนและถูกเรียกเก็บเงิน

ส่วนลดคือเท่าไหร่

Batch API ให้ส่วนลด 50% เมื่อเทียบกับ synchronous endpoints สำหรับโทเค็นขาเข้าและขาออก เหมาะกับงาน offline ที่มี volume สูง

ถ้าต้องการแบ่งต้นทุนกลับไปยัง feature หรือ job ต่าง ๆ ดู คู่มือการจัดสรรต้นทุน

ใช้ endpoint ใดใน Batch API ได้บ้าง

คุณต้องตั้ง endpoint ให้ตรงกันทั้งใน:

url ของแต่ละบรรทัดใน JSONL
endpoint ตอนสร้าง batch

ตัวอย่าง endpoint ที่รองรับ:

/v1/chat/completions
/v1/responses
/v1/embeddings
/v1/completions
/v1/moderations

รวมถึง endpoints รูปภาพและวิดีโอบางส่วน ควรตรวจเอกสาร OpenAI ล่าสุดก่อนใช้งานจริง เพราะรายการ endpoint อาจมีการอัปเดต

ทำไมผลลัพธ์ไม่เรียงตาม input

เป็น behavior ปกติของ Batch API ไฟล์ output ไม่รับประกันลำดับเดียวกับไฟล์ input

ให้ใช้ custom_id เพื่อ map ผลลัพธ์กลับไปยัง request เดิมเสมอ ห้ามอ้างอิงจากลำดับบรรทัด

ถ้า request บางรายการล้มเหลวต้องทำอย่างไร

ตรวจสอบทั้ง:

output_file_id: request ที่มีผลลัพธ์
error_file_id: request ที่ error

จากนั้นใช้ custom_id เพื่อแยกเฉพาะรายการที่ล้มเหลว แล้วสร้าง JSONL ใหม่สำหรับ retry เฉพาะ request เหล่านั้น

บทสรุป

Flow หลักของ OpenAI Batch API คือ:

สร้างไฟล์ JSONL
อัปโหลดด้วย POST /v1/files
สร้าง batch ด้วย POST /v1/batches
poll สถานะด้วย GET /v1/batches/{id}
ดาวน์โหลด output ด้วย GET /v1/files/{id}/content
parse ผลลัพธ์ด้วย custom_id

Batch API เหมาะกับงาน offline ปริมาณมากที่รับ latency ได้สูงสุด 24 ชั่วโมง และต้องการลดต้นทุน token ลง 50%

ก่อน automate ใน production ให้รัน lifecycle ด้วยตนเองใน Apidog เพื่อตรวจ JSONL, ทดสอบ upload, สร้าง batch, poll สถานะ, ทดสอบ cancel/error path และยืนยัน response fields ให้ครบก่อนปล่อยงานจริงขนาดใหญ่

DEV Community