Copy

Penggunaan

Anda dapat memanggil antarmuka file menggunakan OpenAI SDK dengan Python atau Java, atau melalui panggilan API HTTP. Operasi yang didukung mencakup mengunggah, membuat kueri, dan menghapus file.

Prasyarat

Kunci API Alibaba Cloud Model Studio: Buat kunci API dan Ekspor kunci API sebagai variabel lingkungan.
Untuk menggunakan SDK OpenAI, instal SDK OpenAI.

Ketersediaan model

Anda dapat menggunakan file ID dalam skenario berikut:

Qwen-Long: Melakukan tanya jawab pada dokumen yang panjang.
Qwen-Doc-Turbo: Mengekstraksi data dan melakukan tanya jawab pada file.
Pemrosesan batch: Mengunggah file dalam batch.

Memulai

Mengunggahfile

Ruang penyimpanan Model Studio mendukung maksimum 10.000 file dengan total ukuran hingga 100 GB. File tidak akan kedaluwarsa.

Untuk analisis dokumen
Untuk batch processing

Atur purpose ke file-extract. Format file yang didukung meliputi file teks (seperti TXT, DOCX, PDF, XLSX, EPUB, MOBI, MD, CSV, dan JSON) dan file gambar (seperti BMP, PNG, JPG/JPEG, GIF, dan PDF hasil pindaian). Ukuran maksimum untuk satu file adalah 150 MB.

Untuk informasi lebih lanjut tentang analisis dokumen menggunakan file_id, lihat konteks panjang (Qwen-Long).

Contohrequest

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan api_key="sk-xxx" dan gunakan kunci API Model Studio Anda.
    # Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# test.txt adalah file contoh lokal.
file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())

Contohrespons

{
    "id": "file-fe-xxx",
    "bytes": 2055,
    "created_at": 1729065448,
    "filename": "test.txt",
    "object": "file",
    "purpose": "file-extract",
    "status": "processed",
    "status_details": null
}

Jika Anda mengatur purpose ke batch, file input harus berupa file JSONL dan mematuhi persyaratan file batch. Ukuran maksimum untuk satu file untuk tugas batch adalah 500 MB.

Untuk informasi lebih lanjut tentang panggilan batch, lihat OpenAI-compatible - Batch (masukan file).

Contohrequest

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan api_key="sk-xxx" dan gunakan Kunci API Model Studio Anda.
    # Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# test.jsonl adalah file contoh lokal.
file_object = client.files.create(file=Path("test.jsonl"), purpose="batch")

print(file_object.model_dump_json())

Contohrespons

{
    "id": "file-batch-xxx",
    "bytes": 231,
    "created_at": 1729065815,
    "filename": "test.jsonl",
    "object": "file",
    "purpose": "batch",
    "status": "processed",
    "status_details": null
}

Kueri informasi file

Buat kueri informasi file dengan menentukan file_id dalam metode retrieve atau GET.

OpenAI Python SDK
OpenAI Java SDK
HTTP

Contoh request

import os
from openai import OpenAI

client = OpenAI(
    # Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

file = client.files.retrieve(file_id="file-batch-xxx")

print(file.model_dump_json())

Contohrespons

{
  "id": "file-batch-xxx",
  "bytes": 27,
  "created_at": 1722480306,
  "filename": "test.txt",
  "object": "file",
  "purpose": "batch",
  "status": "processed",
  "status_details": null
}

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileObject;
import com.openai.models.FileRetrieveParams;

public class Main {
    public static void main(String[] args) {
        // Buat klien dan gunakan kunci API dari variabel lingkungan.
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // Buat parameter kueri file. Ganti fileId sesuai kebutuhan.
        FileRetrieveParams params= FileRetrieveParams.builder()
                .fileId("file-batch-xxx")
                .build();
        //Kueri file.
        FileObject fileObject = client.files().retrieve(params);
        System.out.println(fileObject);
    }
}

Endpoint

Wilayah Singapura: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}
Wilayah Tiongkok (Beijing): GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

Contohrequest

# ======= Penting =======
# Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx
# === Hapus komentar ini sebelum menjalankan ===
curl -X GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

Jika Anda menggunakan model di wilayah Tiongkok (Beijing), Anda harus menggunakan KUNCI API dari wilayah Tiongkok (Beijing) dan mengganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx

Contohrespons

{
    "id": "file-batch-xxx",
    "object": "file",
    "bytes": 499719,
    "created_at": 1715935833,
    "filename": "test.txt",
    "purpose": "batch",
    "status": "processed"
}

Kueri daftar file

Mengembalikan informasi tentang semua file Anda, termasuk file yang diunggah melalui antarmuka unggah dan file hasil dari batch.

Operasi ini mendukung lebih banyak parameter filter. Untuk informasi selengkapnya, lihat Deskripsi parameter.

OpenAI Python SDK
OpenAI Java SDK
HTTP

Contoh request

import os
from openai import OpenAI

client = OpenAI(
    # Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
     # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

file_stk = client.files.list(after="file-batch-xxx",limit=20)
print(file_stk.model_dump_json())

Contohrespons

{
  "data": [
    {
      "id": "file-batch-xxx",
      "bytes": 27,
      "created_at": 1722480543,
      "filename": "test.txt",
      "object": "file",
      "purpose": "batch",
      "status": "processed",
      "status_details": null
    },
    {
      "id": "file-batch-yyy",
      "bytes": 431986,
      "created_at": 1718089390,
      "filename": "test.pdf",
      "object": "file",
      "purpose": "batch",
      "status": "processed",
      "status_details": null
    }
  ],
  "object": "list",
  "has_more": false
}

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileListPage;
import com.openai.models.FileListParams;

public class Main {
    public static void main(String[] args) {
        // Buat klien dan gunakan kunci API dari variabel lingkungan.
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        // Buat parameter kueri daftar file.
        FileListParams params = FileListParams.builder()
                .after("file-batch-xxx")
                .limit(20)
                .build();
        //Kueri daftar file.
        FileListPage file_stk = client.files().list(params);
        System.out.println(file_stk);
    }
}

Endpoint

Wilayah Singapura: GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files
Wilayah Tiongkok (Beijing): GET https://dashscope.aliyuncs.com/compatible-mode/v1/files

Contohrequest

# ======= Penting =======
# Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1/files
# === Hapus komentar ini sebelum menjalankan ===
curl -X GET https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

Jika Anda menggunakan model di wilayah Tiongkok (Beijing), Anda harus menggunakan KUNCI API dari wilayah Tiongkok (Beijing) dan mengganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1/files

Contohrespons

{
    "object": "list",
    "has_more": true,
    "data": [
        {
            "id": "file-batch-xxx",
            "object": "file",
            "bytes": 84889,
            "created_at": 1715569225,
            "filename": "example.txt",
            "purpose": "batch",
            "status": "processed"
        },
        {
            "id": "file-batch-yyy",
            "object": "file",
            "bytes": 722355,
            "created_at": 1715413868,
            "filename": "Agent_survey.pdf",
            "purpose": "batch",
            "status": "processed"
        }
    ]
}

Menghapus file

Menghapus file dengan file_id yang ditentukan. Anda dapat memperoleh informasi file menggunakan API Kueri daftar file.

OpenAI Python SDK
OpenAI Java SDK
HTTP

Contohrequest

import os
from openai import OpenAI

client = OpenAI(
    # Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

file_object = client.files.delete("file-batch-xxx")
print(file_object.model_dump_json())

Contohrespons

{
  "object": "file",
  "deleted": true,
  "id": "file-batch-xxx"
}

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileDeleteParams;
import com.openai.models.FileListPage;
import com.openai.models.FileListParams;

public class Main {
    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
                .build();
        FileDeleteParams params = FileDeleteParams.builder()
                .fileId("file-batch-xxx")
                .build();

        System.out.println(client.files().delete(params));
    }
}

Endpoint

Wilayah Singapura: DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/{file_id}
Wilayah Tiongkok (Beijing): https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

Contohrequest

# ======= Penting =======
# Kunci API untuk wilayah Singapura dan Tiongkok (Beijing) berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Tiongkok (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx
# === Hapus komentar ini sebelum menjalankan ===
curl -X  DELETE https://dashscope-intl.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

Jika Anda menggunakan model dari wilayah Tiongkok (Beijing), Anda harus menggunakan KUNCI API dari wilayah Tiongkok (Beijing) dan mengganti URL dengan: https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch-xxx

Contohrespons

{
  "object": "file",
  "deleted": true,
  "id": "file-batch-oLIon7bzfxELqJBTS5okwC4E"
}

Penagihan

Operasi unggah, penyimpanan, dan kueri file tidak dikenakan biaya. Anda hanya dikenakan biaya untuk token input dan output yang digunakan saat memanggil model.

Pembatasan laju

Batas queries per second (QPS) untuk antarmuka unggah file adalah 3. BTotal batas QPS untuk antarmuka kueri informasi file, kueri daftar file, dan penghapusan file adalah 10.

Going live

Pembersihan berkala: Hapus file yang tidak terpakai secara berkala agar tidak mencapai batas 10.000 file.
Pemeriksaan status: Setelah mengunggah file, periksa statusnya. Pastikan status bernilai processed sebelum menggunakan file tersebut.
Pemeriksaan batas laju: Batas QPS untuk antarmuka unggah file adalah 3. Total batas QPS untuk antarmuka kueri informasi file, kueri daftar file, dan penghapusan file adalah 10.
Penanganankesalahan: Terapkan mekanisme penanganan pengecualian yang komprehensif untuk kesalahan jaringan, kesalahan API, dan masalah lainnya.

FAQ

1. Apa yang harus saya lakukan jika status file tetap "processing" setelah diunggah?

Pemrosesan file memerlukan waktu, tetapi biasanya selesai dalam beberapa detik. Jika status tetap "processing" dalam waktu lama:

Periksa apakah format file didukung.
Periksa apakah ukuran file melebihi batas.
Gunakan API retrieve untuk melakukan kueri status secara berkala.

2.Bisakah ID file digunakan di seluruh akun yang berbeda?

Tidak, tidak bisa. ID file hanya valid dalam akun Alibaba Cloud yang membuatnya dan tidak dapat dibagikan antar akun.

3. Apakah file yang diunggah disimpan secara permanen?

Ya, benar. File yang diunggah disimpan secara permanen di akun Alibaba Cloud Anda kecuali jika Anda menghapusnya. Bersihkan file yang tidak diperlukan secara berkala.

4. Apa saja kemungkinan penyebab kegagalan unggah file?

Kunci API tidak valid atau belum diekspor.
Format file tidak didukung.
Ukuran file melebihi batas (file-extract: 150 MB, batch: 500 MB).
Jumlah maksimum file (10.000) atau batas ukuran total (100 GB) telah tercapai.
Telah melebihi batas QPS untuk antarmuka unggah file. Batasnya adalah 3 QPS.

5. Haruskah saya memilih file-extract atau batch untuk parameter purpose?

file-extract: Gunakan ini untuk skenario analisis dokumen dengan Qwen-Long atau Qwen-Doc-Turbo.
batch: Gunakan ini untuk tugas batch. File harus berupa file JSONL yang memenuhi persyaratan format.

Deskripsi parameter

Kategori	Parameter	Tipe	Wajib	Deskripsi	Contoh
Unggah file	file	File	Ya	File yang akan diunggah.	Path("test.txt")
Unggah file	purpose	String	Ya	Menentukan tujuan file yang diunggah. Nilai yang valid:`file-extract`: Untuk pemahaman dokumen dengan model qwen-long.`batch`: Untuk tugas OpenAI-compatible - Batch (masukan file). File harus dalam format yang ditentukan dalam File batch.	"file-extract"
Kueri file	file_id	String	Ya	ID file yang akan dikueri.	"file-fe-xxx"
	after	String	Tidak	Kursor yang digunakan untuk paginasi dalam tugas Kueri daftar file.Nilai parameter `after` adalah `file_id` dari item terakhir pada halaman saat ini. Ini akan mengambil halaman data berikutnya.Sebagai contoh, jika kueri mengembalikan 20 record dan `file_id` terakhir adalah `file-batch-xxx`, atur `after="file-batch-xxx"` pada kueri berikutnya untuk mengambil halaman daftar selanjutnya.	"file-fe-xxx"
	create_before	String	Tidak	Dalam tugas Kueri daftar file, timestamp dalam format string. Digunakan untuk memfilter dan mengembalikan ID file yang dibuat sebelum waktu yang ditentukan.	`"20250306123000"`, `"2025-11-12 10:10:10"`, `"2025-11-12"`, `"20251112"`
	create_after	String	Tidak	Dalam tugas Kueri daftar file, timestamp dalam format string. Digunakan untuk memfilter dan mengembalikan ID file yang dibuat setelah waktu yang ditentukan.	`"20250306123000"`, `"2025-11-12 10:10:10"`, `"2025-11-12"`, `"20251112"`
	purpose	String	Tidak	Dalam tugas Kueri daftar file, memfilter file berdasarkan tujuannya. Hanya mengembalikan ID file yang sesuai dengan tujuan yang ditentukan (`file-extract` atau `batch`).	"batch"
	limit	Integer	Tidak	Jumlah file yang dikembalikan untuk setiap kueri dalam tugas Kueri daftar file, dengan rentang nilai 1 hingga 2.000 dan nilai default 2.000.	2000
Penghapusan file	file_id	String	Ya	ID file yang akan dihapus.	"file-fe-xxx"
Parameter respons
Parameter respons umum	id	String	\	ID file.Dalam tugas Menghapus file, ini adalah ID file yang berhasil dihapus.	"file-fe-xxx"
	bytes	Integer		Ukuran file dalam byte.	81067
	created_at	Integer		Timestamp UNIX dalam detik saat file dibuat.	1617981067
	filename	String		Nama file yang diunggah.	"text.txt"
	object	String		Tipe objek.Untuk tugas Kueri daftar file, nilainya selalu "list".Dalam tugas lain, nilainya selalu "file".	"file"
	purpose	String		Tujuan file. Nilai yang valid adalah `batch`, `file-extract`, dan `batch_output`.	"file-extract"
	status	String		Status file saat ini.	"processed"
Kueri daftar file	has_more	Boolean		Menunjukkan apakah ada halaman data berikutnya.	false
Kueri daftar file	data	Array		Daftar file yang dikembalikan. Format setiap elemen dalam daftar konsisten dengan parameter respons umum.	`[{ "id": "xxx", "bytes": 27, "created_at": 1722480543, "filename": "test.txt", "object": "file", "purpose": "batch", "status": "processed", "status_details": null }]`
Hapus file	deleted	Boolean		Menunjukkan apakah penghapusan berhasil. Nilai true menandakan keberhasilan.	true

Kode error

Jika panggilan gagal, lihat Kode kesalahan untuk troubleshooting.

​Penggunaan

​Prasyarat

​Ketersediaan model

​Memulai

​Mengunggahfile

Contohrequest

Contohrespons

​Kueri informasi file

Contoh request

Contohrespons

​Kueri daftar file

Contoh request

Contohrespons

​Menghapus file

Contohrequest

Contohrespons

​Penagihan

​Pembatasan laju

​Going live

​FAQ

​1. Apa yang harus saya lakukan jika status file tetap "processing" setelah diunggah?

​2.Bisakah ID file digunakan di seluruh akun yang berbeda?

​3. Apakah file yang diunggah disimpan secara permanen?

​4. Apa saja kemungkinan penyebab kegagalan unggah file?

​5. Haruskah saya memilih file-extract atau batch untuk parameter purpose?

​Deskripsi parameter

​Kode error

Penggunaan

Prasyarat

Ketersediaan model

Memulai

Mengunggahfile

Kueri informasi file

Kueri daftar file

Menghapus file

Penagihan

Pembatasan laju

Going live

FAQ

1. Apa yang harus saya lakukan jika status file tetap "processing" setelah diunggah?

2.Bisakah ID file digunakan di seluruh akun yang berbeda?

3. Apakah file yang diunggah disimpan secara permanen?

4. Apa saja kemungkinan penyebab kegagalan unggah file?

5. Haruskah saya memilih file-extract atau batch untuk parameter purpose?

Deskripsi parameter

Kode error