Skip to main content

Inferensi batch

Untuk skenario inferensi yang tidak memerlukan respons real-time, inferensi batch memproses volume besar permintaan data secara asinkron dengan biaya hanya 50% dari biaya inferensi real-time, dengan API yang kompatibel dengan OpenAI. Cocok untuk pekerjaan batch seperti evaluasi model dan pelabelan data.

Cara kerja

  1. Kirimkan tugas: Unggah file JSONL yang berisi beberapa permintaan untuk membuat tugas inferensi batch.
  2. Pemrosesan asinkron: Sistem memproses tugas dalam antrian latar belakang. Anda dapat memantau progres dan status tugas melalui Konsol atau API.
  3. Unduh hasil: Setelah tugas selesai, sistem menghasilkan file hasil (mencatat respons yang berhasil) dan file error (mencatat detail kegagalan, jika ada).

Cakupan yang berlaku

  • Singapura
  • Tiongkok (Beijing)
Model yang didukung:
  • Model generasi teks
    • Qwen Max: qwen3.8-max, qwen-max
    • Qwen Plus: qwen3.7-plus, qwen-plus
    • Qwen Flash: qwen-flash
  • Model multi-modal
  • Dalam skenario Batch, qwen3.8-max, qwen3.8-flash, qwen3.7-max, qwen3.7-plus, qwen3.6-plus, qwen3.7-flash, qwen3.6-flash, qwen3.5-plus, qwen3.5-flash, qwen3.5-omni-flash, dan qwen3.5-omni-plus mendukung maksimum 256K context token per permintaan. qwen3.5-omni-plus dan qwen3.5-omni-flash tidak mendukung output suara.
  • Beberapa model mendukung mode thinking. Mengaktifkannya menghasilkan thinking tokens, yang meningkatkan biaya.
  • Model seri qwen3.8, qwen3.7, qwen3.6, dan qwen3.5 memiliki mode thinking yang diaktifkan secara default. Saat menggunakan model hybrid thinking, sebaiknya atur parameter enable_thinking secara eksplisit (true untuk mengaktifkan / false untuk menonaktifkan).
  • Dalam badan permintaan JSONL, enable_thinking adalah parameter tingkat atas dari body dan harus diteruskan pada level yang sama dengan model; tidak dapat ditempatkan di dalam extra_body.
  • File hasil inferensi batch tidak memuat bidang reasoning_content. Meskipun enable_thinking=true diatur, choices[0].message dalam file hasil hanya memuat bidang content dan role. Untuk mendapatkan konten proses thinking, gunakan panggilan API real-time (streaming maupun non-streaming dapat; cukup atur enable_thinking=true). Untuk informasi selengkapnya, lihat Deep thinking.

Gunakan inferensi batch

Langkah 1: Siapkan file input

Sebelum membuat tugas, siapkan file JSONL yang memenuhi spesifikasi berikut:
  • Format: JSONL berkode UTF-8 (satu objek JSON independen per baris).
  • Batas ukuran: Maksimal 50.000 permintaan dan 500 MB per file.
    Jika volume data Anda melebihi batas ini, bagi menjadi beberapa tugas dan kirimkan secara terpisah.
  • Batas per baris: Setiap objek JSON harus ≤ 1 MB dan tidak boleh melebihi panjang konteks model.
  • Persyaratan konsistensi: Semua permintaan dalam file yang sama harus menggunakan model yang sama.
  • Pengenal unik: Setiap permintaan harus menyertakan bidang custom_id yang unik dalam file, yang digunakan untuk mencocokkan hasil. custom_id mendukung maksimal 256 karakter; melebihi batas ini menyebabkan validasi tugas gagal. Untuk meneruskan informasi pengenal yang lebih panjang, gunakan bidang kustom dari metadata saat membuat tugas. Untuk informasi selengkapnya, lihat Menggunakan metadata untuk mengembalikan pengenal kustom.
  • Alamat file media: File media yang dirujuk melalui bidang seperti image_url dan video_url dalam body permintaan multimodal harus menggunakan URL yang dapat diakses publik. Jalur file lokal (seperti file:///home/user/test.mp4) dan alamat intranet tidak didukung. Tugas yang dibuat dengan alamat semacam itu dapat dikirimkan dengan sukses tetapi tidak akan pernah diproses hingga selesai. Unggah file ke penyimpanan yang dapat diakses publik terlebih dahulu, lalu rujuk URL-nya.
Setiap objek JSON harus mengikuti spesifikasi bidang berikut:

Bidang

Tipe

Wajib diisi

Deskripsi

custom_id

string

Ya

Pengenal unik permintaan

method

string

Ya

Metode HTTP; hanya POST yang didukung

url

string

Ya

Titik akhir permintaan. Masukkan /v1/chat/completions untuk model generasi teks dan multimodal, dan /v1/embeddings untuk model text embedding

body

object

Ya

Badan permintaan, yang formatnya sama dengan API yang sesuai dengan url yang ditentukan (/v1/chat/completions atau /v1/embeddings)

Contoh file

Anda dapat mengunduh file contoh test_model.jsonl, yang berisi:
{"custom_id":"1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-max","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello!"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-max","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}
Alat pembuatan file JSONL inferensi batch Inferensi batch memerlukan pembuatan file JSONL dengan setiap baris merupakan permintaan independen. Skrip Python berikut dapat dijalankan langsung untuk menghasilkan file JSONL yang sesuai format.

Penggunaan

  1. Simpan kode berikut sebagai generate_batch_jsonl.py
  2. Ubah konten permintaan dalam daftar TASKS dalam skrip
  3. Jalankan python generate_batch_jsonl.py
  4. File batch_input.jsonl yang dihasilkan dapat langsung digunakan untuk tugas inferensi Batch
Skrip pembuatan JSONL model generasi teks
#!/usr/bin/env python3
"""
Batch 推理 JSONL 文件生成工具

支持的地域与模型请参见上方“适用范围”。

文件大小限制:单行 ≤6MB,总文件 ≤500MB,建议 ≤10000 行

使用方式:
  1. 修改下方 TASKS 列表
  2. 运行: python generate_batch_jsonl.py
  3. 输出: batch_input.jsonl
"""
import json

# ═══════════════════════════════════════════════════════
# 配置区:修改以下内容来生成您需要的 JSONL
# ═══════════════════════════════════════════════════════

MODEL = "qwen-max"          # 选择模型(参见上方“适用范围”)
ENABLE_THINKING = False     # 是否开启思考模式(仅部分模型支持)
THINKING_BUDGET = 50        # 思考 token 预算(思考模式下生效)

# 任务列表:每个 dict 代表一条用户消息
TASKS = [
    {"role": "user", "content": "你好!请介绍一下自己。"},
    {"role": "user", "content": "What is 2+2?"},
    {"role": "user", "content": "请用Python写一个快速排序算法"},
]

# ═══════════════════════════════════════════════════════
# 以下为生成逻辑,一般无需修改
# ═══════════════════════════════════════════════════════

def build_request(custom_id: str, model: str, messages: list,
                  enable_thinking: bool = False, thinking_budget: int = 50) -> dict:
    """构造单条 Batch 请求"""
    body = {"model": model, "messages": messages}
    if enable_thinking:
        body["enable_thinking"] = True
        body["thinking_budget"] = thinking_budget
        body["stream"] = True  # 思考模式需开启 stream
    return {
        "custom_id": custom_id,
        "method": "POST",
        "url": "/v1/chat/completions",
        "body": body
    }

def main():
    output_file = "batch_input.jsonl"
    with open(output_file, "w", encoding="utf-8") as f:
        for i, task in enumerate(TASKS, 1):
            messages = [
                {"role": "system", "content": "You are a helpful assistant."},
                task
            ]
            req = build_request(
                custom_id=f"request-{i}",
                model=MODEL,
                messages=messages,
                enable_thinking=ENABLE_THINKING,
                thinking_budget=THINKING_BUDGET
            )
            f.write(json.dumps(req, ensure_ascii=False) + "\n")
    print(f"已生成 {output_file},共 {len(TASKS)} 条请求")

if __name__ == "__main__":
    main()
Format permintaan model multimodal
Bidang content model multimodal berformat array, berisi objek media dan pertanyaan teks. URL media di setiap baris permintaan harus bertipe sama (gambar, video, atau audio). Ganti TASKS dalam skrip di atas dengan format berikut:
# 多模态模型配置示例

# 多模态任务:content 为数组格式
TASKS = [
    {"role": "user", "content": [
        {"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}},
        {"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}},
        {"type": "text", "text": "这些图描绘了什么内容?"}
    ]},
]

# {"type": "input_audio", "input_audio": {"data": "https://example.com/audio.wav", "format": "wav"}}
# {"type": "video_url", "video_url": "https://example.com/video.mp4"}

# 注意:
# - 其他多模态模型包含 system 角色,thinking_budget 设置为 50
# - 思考模式需额外设置 ENABLE_THINKING = True
Format permintaan model text embedding
Model text embedding menggunakan API /v1/embeddings, dan format permintaannya berbeda dari model generasi teks. Anda dapat menggunakan skrip mandiri berikut untuk membuatnya:
#!/usr/bin/env python3
"""文本向量模型 Batch JSONL 生成(使用 /v1/embeddings 接口)"""
import json

MODEL = "text-embedding-v3"  # 向量模型,可选型号参见上方“适用范围”

TEXTS = [
    "衣服的质量杠杠的,很漂亮,不枉我等了这么久啊,喜欢,以后还来这里买。",
    "风急天高猿啸哀",
    "The quick brown fox jumps over the lazy dog",
]

output_file = "batch_embedding.jsonl"
with open(output_file, "w", encoding="utf-8") as f:
    for i, text in enumerate(TEXTS, 1):
        req = {
            "custom_id": f"emb-{i}",
            "method": "POST",
            "url": "/v1/embeddings",
            "body": {"model": MODEL, "input": text, "encoding_format": "float"}
        }
        f.write(json.dumps(req, ensure_ascii=False) + "\n")
print(f"已生成 {output_file},共 {len(TEXTS)} 条请求")

Konfigurasikan mode thinking dalam inferensi batch

Beberapa model (seperti qwen3.7-plus, qwen3.7-max, dan seri qwen3.6 serta qwen3.5) memiliki mode thinking yang diaktifkan secara default, yang menghasilkan token thinking tambahan. Untuk mengonfigurasi mode thinking dalam inferensi batch, atur parameter enable_thinking dalam body setiap baris permintaan pada file JSONL, ditempatkan pada level yang sama dengan model. Parameter opsional thinking_budget digunakan untuk membatasi jumlah maksimum token thinking.
enable_thinking dan thinking_budget harus ditempatkan langsung di tingkat atas body (pada level yang sama dengan model). Jangan letakkan di dalam extra_body — extra_body adalah mekanisme yang digunakan OpenAI Python SDK untuk meneruskan parameter non-standar, yang hanya berfungsi dalam panggilan SDK untuk inferensi real-time dan tidak berlaku untuk file JSONL inferensi batch.
Contoh: Nonaktifkan mode thinking
{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen3.5-plus","enable_thinking":false,"messages":[{"role":"user","content":"你好"}]}}
Contoh: Aktifkan mode thinking dan batasi anggaran token thinking
{"custom_id":"request-2","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen3.5-plus","enable_thinking":true,"thinking_budget":50,"messages":[{"role":"user","content":"请分析以下问题"}]}}

Langkah 2: Buat tugas inferensi batch

  1. Di halaman **Inferensi batch**, klik Create Batch.
  2. Dalam kotak dialog yang muncul: masukkan Task Name dan Task Description, atur Maximum Waiting Time (1–14 hari), dan unggah file JSONL.
    Anda dapat mengklik Download Sample File untuk mendapatkan templat.
  3. Setelah melengkapi formulir, klik Confirm.

Langkah 3: Pantau dan kelola tugas

  • Lihat:
    • Di halaman Tasks, lihat progres (jumlah permintaan yang diproses/jumlah total permintaan) dan status suatu tugas.
    • Cari berdasarkan nama atau ID tugas, atau filter berdasarkan ruang kerja untuk menemukan tugas target dengan cepat.
  • Kelola:
    • Batalkan: tugas dalam status "Running" dapat dibatalkan di kolom Actions.

Langkah 4: Unduh hasil

Tugas dihapus secara otomatis 30 hari setelah selesai. Unduh hasil secara tepat waktu.
Setelah tugas selesai, klik View Results untuk mengunduh file output:
  • File hasil: mencatat semua permintaan yang berhasil beserta hasil response-nya.
  • File error (jika ada): mencatat semua permintaan yang gagal beserta detail error-nya.
Kedua file berisi bidang custom_id, yang digunakan untuk mencocokkan data input asli, mengaitkan hasil, atau menemukan error.

Langkah 5: Lihat statistik penggunaan (Opsional)

Di halaman Monitoring, filter dan lihat statistik penggunaan inferensi batch.
  • Lihat ikhtisar data: pilih waktu (hingga 30 hari), atur Inference Type ke Batch Inference, dan Anda dapat melihat:
    • Data Pemantauan: Statistik ringkasan semua model dalam periode waktu tersebut, seperti jumlah total panggilan dan jumlah total kegagalan.
    • Model: Data detail setiap model, seperti total panggilan, tingkat kegagalan, dan durasi panggilan rata-rata.
    Untuk melihat data inferensi lebih dari 30 hari ke belakang, buka halaman Bill.
  • Lihat detail model: Di daftar Models, klik Monitoring di kolom Actions pada model target untuk melihat detail Call Statistics (seperti jumlah panggilan dan volume panggilan).
    image
  • Data panggilan inferensi batch dihitung berdasarkan waktu selesai tugas. Untuk tugas yang sedang berjalan, informasi panggilan tidak dapat dikueri sampai tugas selesai.
  • Data pemantauan mengalami keterlambatan 1 hingga 2 jam.

Gunakan metadata untuk mengembalikan pengenal kustom

custom_id mendukung hingga 256 karakter. Untuk mengembalikan informasi pengenal yang lebih panjang dalam file hasil, Anda dapat menggunakan bidang kustom dari metadata.

Bidang metadata

metadata adalah parameter opsional saat membuat tugas Batch dan mendukung bidang berikut:
  • ds_name: Nama tugas. Setelah diatur, ditampilkan di kolom Task Name di Konsol.
  • ds_description: Deskripsi tugas. Setelah diatur, ditampilkan di kolom Task Description di Konsol.
  • Bidang kustom: Selain bidang resmi di atas, metadata juga mendukung bidang kustom apa pun, dan nilai bidang kustom tidak dibatasi 256 karakter. Saat Anda mengkueri detail tugas, semua bidang kustom dikembalikan secara lengkap.

Contoh kode

Contoh berikut menunjukkan cara mengembalikan informasi pengenal yang lebih panjang dari 256 karakter melalui bidang kustom dari metadata:
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

batch = client.batches.create(
    input_file_id="file-batch-xxxxxxxxxxxxxxxxxxxx",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "ds_name": "my_batch_task",
        "ds_description": "批量推理任务描述",
        "my_custom_field": "此字段的值可以超过256个字符,用于回传更长的标识信息..."
    }
)
print(batch)
Setelah tugas dibuat, Anda dapat memanggil API kueri detail tugas (GET /v1/batches/{batch_id}) untuk mendapatkan informasi metadata lengkap, termasuk semua bidang kustom beserta konten lengkapnya.

Referensi API

Di lingkungan produksi, gunakan API yang kompatibel dengan OpenAI untuk membuat dan mengelola tugas Batch secara otomatis. Alur kerja intinya adalah sebagai berikut:
Inferensi batch hanya mendukung panggilan API dalam format kompatibel OpenAI. Saat menggunakan OpenAI Python SDK, atur base_url ke https://dashscope.aliyuncs.com/compatible-mode/v1. DashScope Python SDK (paket dashscope) tidak menyediakan antarmuka inferensi batch, sehingga tugas inferensi batch tidak dapat dikirimkan melalui dashscope.BatchInference, dashscope.Batches, atau metode serupa.
Contoh:
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.create(
    input_file_id=file_id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
  1. Unggah file Panggil POST /v1/files untuk mengunggah file dan catat ID file yang dikembalikan.
  2. Buat tugas Masukkan ID file dan panggil POST /v1/batches untuk membuat tugas, lalu catat batch_id yang dikembalikan.
  3. Periksa status Gunakan batch_id untuk melakukan polling GET /v1/batches/{batch_id}. Saat status berubah menjadi completed, catat output_file_id dan hentikan polling.
  4. Unduh hasil Gunakan output_file_id untuk memanggil GET /v1/files/{output_file_id}/content dan mengunduh file hasil.
Untuk definisi lengkap API Batch dan contoh kode, lihat Batch kompatibel OpenAI (input file).

Siklus hidup tugas

Status

Deskripsi

validating (Verifying)

Sistem sedang memvalidasi format file (spesifikasi JSONL) dan validitas format API setiap baris permintaan.

in_progress (Running)

File telah lolos validasi, dan sistem telah mulai memproses permintaan inferensi baris demi baris.

finalizing (Running)

Semua permintaan telah diproses, dan hasil sedang ditulis ke file hasil dan file error. Di daftar tugas Konsol, tahap ini berbagi label status Running dengan in_progress dan tidak memiliki teks tampilan terpisah.

completed (Completed)

File hasil dan file error telah ditulis dan siap untuk diunduh.

failed

Tugas gagal selama tahap validating, biasanya karena error tingkat file (seperti format JSONL tidak valid atau ukuran file terlalu besar). Dalam status ini, tidak ada permintaan inferensi yang dieksekusi dan tidak ada file hasil yang dihasilkan.

expired

Waktu berjalan tugas melebihi waktu tunggu maksimum yang ditetapkan saat pembuatan dan dihentikan oleh sistem. Saat membuat tugas baru, sebaiknya atur waktu tunggu yang lebih lama.

cancelled

Pengguna membatalkan tugas, dan permintaan yang belum mulai diproses akan dihentikan.

Detail penagihan

  • Harga satuan penagihan: Untuk semua permintaan yang berhasil, harga satuan token input dan output adalah 50% dari harga inferensi real-time model yang bersangkutan. Untuk informasi selengkapnya, lihat Model.
  • Cakupan penagihan:
    • Hanya permintaan yang berhasil dieksekusi dalam tugas yang ditagih.
    • Kegagalan parsing file, kegagalan eksekusi tugas, atau permintaan yang salah pada tingkat baris tidak dikenai biaya.
    • Untuk tugas yang dibatalkan, permintaan yang berhasil diselesaikan sebelum pembatalan tetap ditagih secara normal.
  • Inferensi batch adalah item penagihan mandiri. Item ini mendukung AI Universal Savings Plan, tetapi tidak mendukung diskon seperti prabayar (savings plan) dan kuota gratis pengguna baru, atau fitur seperti context cache.
  • Beberapa model (seperti qwen3.7-plus, qwen3.7-max, dan seri qwen3.6 serta qwen3.5) memiliki mode thinking yang diaktifkan secara default, yang menghasilkan token thinking tambahan yang ditagih dengan harga token output, sehingga meningkatkan biaya. Sebaiknya atur parameter enable_thinking berdasarkan kompleksitas tugas untuk mengontrol biaya. Untuk informasi selengkapnya, lihat deep thinking.

FAQ

  1. Apakah saya perlu melakukan pembelian atau aktivasi tambahan untuk menggunakan inferensi batch? Tidak. Anda dapat menggunakannya setelah Alibaba Cloud Model Studio diaktifkan, dan biaya dipotong dari saldo akun Anda berdasarkan model pay-as-you-go.
  2. Mengapa tugas gagal segera setelah dikirimkan (status berubah menjadi failed)? Hal ini biasanya disebabkan oleh error tingkat file, dan tugas tidak mengeksekusi permintaan inferensi apa pun. Pecahkan masalah dengan urutan berikut:
    • Format file: Apakah format JSONL ketat, dengan satu objek JSON lengkap per baris?
    • Ukuran file: Apakah ukuran file, jumlah baris, dll. melebihi batas? Untuk informasi selengkapnya, lihat Siapkan file input.
    • Konsistensi model: Periksa bahwa bidang body.model dari semua permintaan dalam file benar-benar sama, dan model yang digunakan didukung di wilayah saat ini.
  3. Berapa lama waktu pemrosesan tugas? Waktu pemrosesan terutama bergantung pada beban sistem saat itu. Saat sistem sibuk, tugas mungkin harus mengantri, tetapi hasil, baik sukses maupun gagal, akan dikembalikan dalam waktu tunggu maksimum yang ditetapkan.

Kode error

Jika panggilan gagal dan mengembalikan pesan error, lihat Kode error untuk pemecahan masalah.