Model multimodal seperti Qwen-VL memerlukan URL file sebagai input gambar, video, dan audio. Model Studio menyediakan ruang penyimpanan sementara gratis bagi pengguna yang tidak memiliki URL publik: unggah file dan dapatkan URL oss:// yang berlaku selama 48 jam .
URL sementara hanya untuk pengembangan dan pengujian—tidak untuk skenario produksi, konkurensi tinggi, atau uji stres. Untuk beban kerja produksi, gunakan Object Storage Service (OSS) agar tersedia dalam jangka panjang dan menghindari batas laju.
Fitur ini hanya tersedia di wilayah China (Beijing). Gunakan API key dari wilayah ini.
Unggah file dan tentukan model target. API akan mengembalikan URL oss://.
Gunakan URL tersebut dalam pemanggilan model Anda. Anda harus menyelesaikan Langkah 2 untuk menggunakan URL sementara—melewatkannya akan menyebabkan error. Untuk panggilan HTTP, tambahkan header X-DashScope-OssResourceResolve: enable. SDK DashScope menambahkan header ini secara otomatis.
Tentukan nama model saat mengunggah. Gunakan model yang sama dalam panggilan berikutnya—file tidak dapat dibagikan lintas model.
Batas Ukuran File
Ukuran file tidak boleh melebihi 1GB dan juga harus mematuhi batas spesifik model yang dipilih.
Pengikatan file-akun
API key untuk unggah dan panggilan model harus berasal dari Akun Alibaba Cloud yang sama—file tidak dapat dibagikan lintas akun.
Kedaluwarsa 48 jam
File dihapus secara otomatis setelah 48 jam. Selesaikan panggilan model dalam periode ini.
Tidak ada manajemen pasca-unggah
File tidak dapat diinterogasi, dimodifikasi, atau diunduh—file hanya berfungsi sebagai parameter URL dalam panggilan model.
Batas laju
API kredensial unggah dibatasi hingga 100 QPS per akun per model. Permintaan berlebih akan gagal. Ruang penyimpanan sementara tidak mendukung scale-out.
Unggah file dan dapatkan URL sementaranya menggunakan salah satu metode berikut:
Unggah dengan kode
Unggah dengan CLI
Python
Java
Prasyarat
Python 3.9 atau lebih baru
Instal dependensi:
Copy
pip install -U requests
Parameter
Parameter
Deskripsi
Contoh
api_key
Model Studio API key
Dibaca dari variabel lingkungan DASHSCOPE_API_KEY
model_name
Model yang akan menggunakan file tersebut
qwen-vl-plus
file_path
Jalur ke file lokal
/tmp/cat.png
Kode contoh
Copy
import osimport requestsfrom pathlib import Pathfrom datetime import datetime, timedeltadef get_upload_policy(api_key, model_name): """Dapatkan kredensial unggah file.""" url = "https://dashscope-intl.aliyuncs.com/api/v1/uploads" headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } params = { "action": "getPolicy", "model": model_name } response = requests.get(url, headers=headers, params=params) if response.status_code != 200: raise Exception(f"Gagal mendapatkan kebijakan unggah: {response.text}") return response.json()['data']def upload_file_to_oss(policy_data, file_path): """Unggah file ke penyimpanan OSS sementara.""" file_name = Path(file_path).name key = f"{policy_data['upload_dir']}/{file_name}" with open(file_path, 'rb') as file: files = { 'OSSAccessKeyId': (None, policy_data['oss_access_key_id']), 'Signature': (None, policy_data['signature']), 'policy': (None, policy_data['policy']), 'x-oss-object-acl': (None, policy_data['x_oss_object_acl']), 'x-oss-forbid-overwrite': (None, policy_data['x_oss_forbid_overwrite']), 'key': (None, key), 'success_action_status': (None, '200'), 'file': (file_name, file) } response = requests.post(policy_data['upload_host'], files=files) if response.status_code != 200: raise Exception(f"Gagal mengunggah file: {response.text}") return f"oss://{key}"def upload_file_and_get_url(api_key, model_name, file_path): """Unggah file dan dapatkan URL-nya.""" # 1. Dapatkan kredensial unggah (dibatasi laju hingga 100 QPS) policy_data = get_upload_policy(api_key, model_name) # 2. Unggah file ke OSS oss_url = upload_file_to_oss(policy_data, file_path) return oss_url# Contohif __name__ == "__main__": # Baca API key dari variabel lingkungan api_key = os.getenv("DASHSCOPE_API_KEY") if not api_key: raise Exception("Atur variabel lingkungan DASHSCOPE_API_KEY.") # Atur nama model model_name="qwen-vl-plus" # Ganti dengan jalur file sebenarnya file_path = "/tmp/cat.png" try: public_url = upload_file_and_get_url(api_key, model_name, file_path) expire_time = datetime.now() + timedelta(hours=48) print(f"File berhasil diunggah. URL berlaku selama 48 jam.") print(f"Waktu kedaluwarsa: {expire_time.strftime('%Y-%m-%d %H:%M:%S')}") print(f"URL sementara: {public_url}") print("Catatan: Saat menggunakan URL sementara dengan awalan oss://, Anda harus menambahkan parameter X-DashScope-OssResourceResolve: enable ke header permintaan HTTP. Untuk informasi lebih lanjut, lihat https://www.alibabacloud.com/help/en/model-studio/get-temporary-file-url#http-call") except Exception as e: print(f"Error: {str(e)}")
Output contoh
Copy
File berhasil diunggah. URL berlaku selama 48 jam.Waktu kedaluwarsa: 2024-07-18 17:36:15URL sementara: oss://dashscope-instant/xxx/2024-07-18/xxx/cat.pngCatatan: Saat menggunakan URL sementara dengan awalan oss://, Anda harus menambahkan parameter X-DashScope-OssResourceResolve: enable ke header permintaan HTTP. Untuk informasi lebih lanjut, lihat https://www.alibabacloud.com/help/en/model-studio/get-temporary-file-url#http-call
Setelah mendapatkan URL sementara, tambahkan header X-DashScope-OssResourceResolve: enable ke permintaan HTTP saat melakukan panggilan. Untuk informasi lebih lanjut, lihat Panggilan menggunakan HTTP.
import org.apache.http.client.methods.CloseableHttpResponse;import org.apache.http.client.methods.HttpGet;import org.apache.http.client.methods.HttpPost;import org.apache.http.entity.mime.MultipartEntityBuilder;import org.apache.http.entity.ContentType;import org.apache.http.impl.client.CloseableHttpClient;import org.apache.http.impl.client.HttpClients;import org.apache.http.HttpStatus;import org.apache.http.util.EntityUtils;import org.json.JSONObject;import java.io.File;import java.io.IOException;import java.nio.file.Files;import java.nio.file.Path;import java.nio.file.Paths;import java.time.LocalDateTime;import java.time.format.DateTimeFormatter;public class PublicUrlHandler { private static final String API_URL = "https://dashscope-intl.aliyuncs.com/api/v1/uploads"; public static JSONObject getUploadPolicy(String apiKey, String modelName) throws IOException { try (CloseableHttpClient httpClient = HttpClients.createDefault()) { HttpGet httpGet = new HttpGet(API_URL); httpGet.addHeader("Authorization", "Bearer " + apiKey); httpGet.addHeader("Content-Type", "application/json"); String query = String.format("action=getPolicy&model=%s", modelName); httpGet.setURI(httpGet.getURI().resolve(httpGet.getURI() + "?" + query)); try (CloseableHttpResponse response = httpClient.execute(httpGet)) { if (response.getStatusLine().getStatusCode() != 200) { throw new IOException("Gagal mendapatkan kebijakan unggah: " + EntityUtils.toString(response.getEntity())); } String responseBody = EntityUtils.toString(response.getEntity()); return new JSONObject(responseBody).getJSONObject("data"); } } } public static String uploadFileToOSS(JSONObject policyData, String filePath) throws IOException { Path path = Paths.get(filePath); String fileName = path.getFileName().toString(); String key = policyData.getString("upload_dir") + "/" + fileName; HttpPost httpPost = new HttpPost(policyData.getString("upload_host")); MultipartEntityBuilder builder = MultipartEntityBuilder.create(); builder.addTextBody("OSSAccessKeyId", policyData.getString("oss_access_key_id")); builder.addTextBody("Signature", policyData.getString("signature")); builder.addTextBody("policy", policyData.getString("policy")); builder.addTextBody("x-oss-object-acl", policyData.getString("x_oss_object_acl")); builder.addTextBody("x-oss-forbid-overwrite", policyData.getString("x_oss_forbid_overwrite")); builder.addTextBody("key", key); builder.addTextBody("success_action_status", "200"); byte[] fileContent = Files.readAllBytes(path); builder.addBinaryBody("file", fileContent, ContentType.DEFAULT_BINARY, fileName); httpPost.setEntity(builder.build()); try (CloseableHttpClient httpClient = HttpClients.createDefault(); CloseableHttpResponse response = httpClient.execute(httpPost)) { if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) { throw new IOException("Gagal mengunggah file: " + EntityUtils.toString(response.getEntity())); } return "oss://" + key; } } public static String uploadFileAndGetUrl(String apiKey, String modelName, String filePath) throws IOException { JSONObject policyData = getUploadPolicy(apiKey, modelName); return uploadFileToOSS(policyData, filePath); } public static void main(String[] args) { // Baca API key dari variabel lingkungan String apiKey = System.getenv("DASHSCOPE_API_KEY"); if (apiKey == null || apiKey.isEmpty()) { System.err.println("Atur variabel lingkungan DASHSCOPE_API_KEY."); System.exit(1); } // Nama model String modelName = "qwen-vl-plus"; // Ganti dengan jalur file sebenarnya String filePath = "src/main/resources/tmp/cat.png"; try { // Periksa apakah file ada File file = new File(filePath); if (!file.exists()) { System.err.println("File tidak ditemukan: " + filePath); System.exit(1); } String publicUrl = uploadFileAndGetUrl(apiKey, modelName, filePath); LocalDateTime expireTime = LocalDateTime.now().plusHours(48); DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); System.out.println("File berhasil diunggah. URL berlaku selama 48 jam."); System.out.println("Waktu kedaluwarsa: " + expireTime.format(formatter)); System.out.println("URL sementara: " + publicUrl); System.out.println("Catatan: Saat menggunakan URL sementara dengan awalan oss://, Anda harus menambahkan parameter X-DashScope-OssResourceResolve: enable ke header permintaan HTTP. Untuk informasi lebih lanjut, lihat https://www.alibabacloud.com/help/en/model-studio/get-temporary-file-url#http-call"); } catch (IOException e) { System.err.println("Error: " + e.getMessage()); } }}
Contoh output
Copy
File berhasil diunggah. URL berlaku selama 48 jam.Waktu kedaluwarsa: 2024-07-18 17:36:15URL sementara: oss://dashscope-instant/xxx/2024-07-18/xxx/cat.pngCatatan: Saat menggunakan URL sementara dengan awalan oss://, Anda harus menambahkan parameter X-DashScope-OssResourceResolve: enable ke header permintaan HTTP. Untuk informasi lebih lanjut, lihat https://www.alibabacloud.com/help/en/model-studio/get-temporary-file-url#http-call
Setelah mendapatkan URL sementara, tambahkan header X-DashScope-OssResourceResolve: enable ke permintaan HTTP saat melakukan panggilan. Untuk informasi lebih lanjut, lihat Panggilan menggunakan HTTP.
CLI DashScope mengunggah file dengan satu perintah dan mengembalikan URL sementara.Prasyarat
Setelah mendapatkan URL sementara, tambahkan header X-DashScope-OssResourceResolve: enable ke permintaan HTTP saat melakukan panggilan. Untuk informasi lebih lanjut, lihat Panggilan menggunakan HTTP.
Saat memanggil API melalui HTTP (curl, Postman, dll.), tambahkan header ini:
Copy
X-DashScope-OssResourceResolve: enable
Tanpa header ini, API tidak dapat menyelesaikan URL oss:// dan permintaan akan gagal.Contoh permintaanContoh ini memanggil qwen-vl-plus untuk mendeskripsikan gambar yang diunggah.
Ganti oss://... dengan URL sementara Anda yang sebenarnya.
{ "choices": [ { "message": { "content": "This is a picture of a white cat running on the grass. The cat has blue eyes and looks very cute and lively. The background is a blurred natural landscape, which emphasizes the subject: the small cat dashing forward. This photographic technique is called shallow depth of field (or a large aperture effect). It makes the cat in the foreground sharp and clear while blurring the background to highlight the subject and create a dreamlike effect. Overall, this photo feels relaxed and pleasant, and it captures a great moment of the animal's behavior.", "role": "assistant" }, "finish_reason": "stop", "index": 0, "logprobs": null } ], "object": "chat.completion", "usage": { "prompt_tokens": 1253, "completion_tokens": 104, "total_tokens": 1357 }, "created": 1739349052, "system_fingerprint": null, "model": "qwen-vl-plus", "id": "chatcmpl-cfc4f2aa-22a8-9a94-8243-44c5bd9899bc"}
SDK DashScope menangani header X-DashScope-OssResourceResolve secara otomatis—berikan URL oss:// langsung sebagai parameter file.
SDK OpenAI tidak didukung. Tidak semua model mendukung panggilan SDK—lihat referensi API model tertentu untuk detailnya.
Python
Java
Prasyarat:DashScope Python SDK1.24.0 atau lebih baru.Contoh ini memanggil qwen-vl-plus untuk mendeskripsikan gambar yang diunggah. Kode ini berlaku untuk model qwen-vl dan omni.
Ganti oss://... pada parameter gambar dengan URL sementara Anda yang sebenarnya.
Copy
import osimport dashscopemessages = [ { "role": "system", "content": [{"text": "You are a helpful assistant."}] }, { "role": "user", "content": [ {"image": "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"}, {"text": "What is this?"}] }]# Jika tidak dikonfigurasi sebagai variabel lingkungan, ganti dengan: api_key="sk-xxx"api_key = os.getenv('DASHSCOPE_API_KEY')response = dashscope.MultiModalConversation.call( api_key=api_key, model='qwen-vl-plus', messages=messages)print(response)
Contoh respons
Copy
{ "status_code": 200, "request_id": "ccd9dcfb-98f0-92bc-xxxxxx", "code": "", "message": "", "output": { "text": null, "finish_reason": null, "choices": [ { "finish_reason": "stop", "message": { "role": "assistant", "content": [ { "text": "This is a photo of a cat running on the grass. The cat's fur is mainly white with light brown spots, and its eyes are blue, making it look very cute. The background is a blurry green meadow with some trees, and the sunlight adds a warm feeling to the whole picture. The cat's posture shows that it is moving quickly, possibly chasing something or just enjoying the outdoors. Overall, this is a vibrant and lively picture." } ] } } ] }, "usage": { "input_tokens": 1112, "output_tokens": 91, "input_tokens_details": { "text_tokens": 21, "image_tokens": 1091 }, "prompt_tokens_details": { "cached_tokens": 0 }, "total_tokens": 1203, "output_tokens_details": { "text_tokens": 91 }, "image_tokens": 1091 }}
Prasyarat:DashScope Java SDK2.21.0 atau lebih baru.Contoh ini memanggil qwen-vl-plus untuk mendeskripsikan gambar yang diunggah. Kode ini berlaku untuk model qwen-vl dan omni.
Ganti oss://... dengan URL sementara Anda yang sebenarnya.
Copy
import com.alibaba.dashscope.aigc.multimodalconversation.*;import com.alibaba.dashscope.common.Role;import com.alibaba.dashscope.exception.ApiException;import com.alibaba.dashscope.exception.NoApiKeyException;import com.alibaba.dashscope.exception.UploadFileException;import com.alibaba.dashscope.utils.JsonUtils;import java.util.Arrays;public class MultiModalConversationUsage { private static final String modelName = "qwen-vl-plus"; // Jika tidak dikonfigurasi sebagai variabel lingkungan, ganti dengan: api_key="sk-xxx" public static String apiKey = System.getenv("DASHSCOPE_API_KEY"); public static void simpleMultiModalConversationCall() throws ApiException, NoApiKeyException, UploadFileException { MultiModalConversation conv = new MultiModalConversation(); MultiModalMessageItemText systemText = new MultiModalMessageItemText("You are a helpful assistant."); MultiModalConversationMessage systemMessage = MultiModalConversationMessage.builder() .role(Role.SYSTEM.getValue()).content(Arrays.asList(systemText)).build(); MultiModalMessageItemImage userImage = new MultiModalMessageItemImage( "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"); MultiModalMessageItemText userText = new MultiModalMessageItemText("What is this?"); MultiModalConversationMessage userMessage = MultiModalConversationMessage.builder().role(Role.USER.getValue()) .content(Arrays.asList(userImage, userText)).build(); MultiModalConversationParam param = MultiModalConversationParam.builder() .model(MultiModalConversationUsage.modelName) .apiKey(apiKey) .message(systemMessage) .vlHighResolutionImages(true) .vlEnableImageHwOutput(true)// .incrementalOutput(true) .message(userMessage).build(); MultiModalConversationResult result = conv.call(param); System.out.print(JsonUtils.toJson(result)); } public static void main(String[] args) { try { simpleMultiModalConversationCall(); } catch (ApiException | NoApiKeyException | UploadFileException e) { System.out.println(e.getMessage()); } System.exit(0); }}
Contoh respons
Copy
{ "requestId": "b6d60f91-4a7f-9257-xxxxxx", "usage": { "input_tokens": 1112, "output_tokens": 91, "total_tokens": 1203, "image_tokens": 1091, "input_tokens_details": { "text_tokens": 21, "image_tokens": 1091 }, "output_tokens_details": { "text_tokens": 91 } }, "output": { "choices": [ { "finish_reason": "stop", "message": { "role": "assistant", "content": [ { "text": "This is a photo of a cat running on the grass. The cat's fur is mainly white with light brown spots, and its eyes are blue, making it look very cute. The background is a blurry green meadow with some trees, and the sunlight adds a warm feeling to the whole picture. The cat's posture shows that it is moving quickly, possibly chasing something or just enjoying the outdoors. Overall, this is a vibrant and lively picture." }, { "image_hw": [ [ "924", "924" ] ] } ] } } ] }}
Kode contoh dan CLI pada Langkah 1 membungkus tiga operasi API berikut secara internal. Gunakan referensi ini untuk mengimplementasikan alur unggah secara manual.
API kredensial dibatasi laju hingga 100 QPS per akun per model. Ruang penyimpanan sementara tidak dapat diperluas kapasitasnya. Untuk beban kerja produksi atau konkurensi tinggi, gunakan Alibaba Cloud OSS.
Apa yang harus saya lakukan jika URL oss:// mengembalikan error?
Ikuti langkah-langkah berikut:
Periksa header permintaan. Jika memanggil API melalui HTTP (curl, Postman, dll.), tambahkan X-DashScope-OssResourceResolve: enable ke header permintaan. Tanpa header ini, server tidak dapat menyelesaikan protokol oss://. SDK DashScope menambahkan header ini secara otomatis.
Periksa masa berlaku URL. URL oss:// kedaluwarsa 48 jam setelah diunggah. Jika sudah kedaluwarsa, unggah ulang file untuk mendapatkan URL baru.
Apakah saya bisa menggunakan API key berbeda untuk unggah file dan panggilan model?
Ya, selama kedua API key berasal dari Akun Alibaba Cloud yang sama. Akses file dikelola di tingkat akun, bukan tingkat API key.API key dari Akun Alibaba Cloud yang berbeda tidak dapat mengakses file yang diunggah oleh akun lain.