Alibaba Cloud Model Studio proporciona una API de Batch File compatible con OpenAI. Envíe solicitudes en masa a través de archivos. El sistema las procesa asincrónicamente y devuelve resultados cuando todas las solicitudes se completan o se alcanza el tiempo máximo de espera. Los costos son solo del 50% de las llamadas en tiempo real. Ideal para análisis de datos, evaluación de modelos y otras cargas de trabajo a gran escala donde la latencia no es crítica.
Flujo de trabajo
Requisitos previos
Puede llamar a la API Batch File a través del SDK de OpenAI (Python, Node.js) o la API HTTP.
- Obtener una clave API: Obtenga y configure su clave API de Model Studio como variable de entorno
- Instalar SDK (opcional): Instale el SDK de OpenAI si planea utilizarlo.
-
Endpoints de servicio
- Norte de China 2 (Beijing):
https://dashscope.aliyuncs.com/compatible-mode/v1 - Singapur:
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
- Norte de China 2 (Beijing):
Ámbito
- Singapore
- China (Beijing)
Introducción
Antes de procesar tareas formales, realice pruebas con el batch-test-model. Este modelo de prueba omite la inferencia y devuelve una respuesta de éxito fija, lo que le permite verificar su cadena de llamadas API y el formato de datos.
- Su archivo de prueba debe cumplir con los Requisitos del archivo de entrada. Tamaño máximo: 1 MB. Líneas máximas: 100.
- Límite de concurrencia: Hasta 2 tareas paralelas.
- Costo: El modelo de prueba no genera cargos por inferencia del modelo.
Paso 1: Preparar el archivo de entrada
Prepare un archivo llamado test_model.jsonl con el siguiente contenido:
Paso 2: Ejecutar el código
Seleccione un fragmento de código para su lenguaje de programación. Guárdelo en el mismo directorio que su archivo de entrada y ejecútelo. El código maneja el flujo de trabajo completo: carga, creación de tarea, sondeo de estado y descarga de resultados.
Para personalizar la ruta del archivo u otros parámetros, modifique el código según sea necesario.
file-batch-xxx) se puede reutilizar. Si el contenido de entrada permanece igual, omita la recarga y cree directamente una tarea con el ID existente:client.files.list(purpose="batch") para consultar ID de archivos Batch cargados.Código de ejemplo
Código de ejemplo
Paso 3: Verificar resultados de la prueba
Después de que la tarea tenga éxito, el archivo de resultados result.jsonl contiene la respuesta fija {"content":"This is a test result."}:
Ejecutar una tarea formal
Requisitos del archivo de entrada
- Formato: JSONL codificado en UTF-8 (un objeto JSON independiente por línea).
- Límites de tamaño: Máximo 50,000 solicitudes por archivo, máximo 500 MB.
- Límite de líneas: Cada objeto JSON no debe exceder 6 MB y debe caber dentro de la ventana de contexto del modelo.
- Consistencia: Todas las solicitudes en el mismo archivo deben utilizar el mismo modelo y el mismo modo de pensamiento (si corresponde).
- Identificador único: Cada solicitud debe incluir un campo custom_id único dentro del archivo. Este campo se utiliza para hacer coincidir las solicitudes con los resultados.
Las cadenas Base64 en los ejemplos anteriores están truncadas. Genere codificaciones completas utilizando el código Python a continuación.
Pasar cadenas codificadas en Base64 (usando imágenes como ejemplo)
Pasar cadenas codificadas en Base64 (usando imágenes como ejemplo)
- Convertir un archivo local a codificación Base64:
-
Construya un formato Data URL:
data:[MIME_type];base64,{base64_image};- Reemplace
MIME_typecon el tipo de medio real. Debe coincidir con el valor deMIME Type(p. ej.,image/jpeg,image/png); base64_imagees la cadena Base64 generada en el paso anterior.
- Reemplace
1. Modificar el archivo de entrada
-
En el archivo
test_model.jsonl, configure el parámetromodelal modelo objetivo y configure el campourl:Tipo de modelo
url
Modelos de generación de texto/multimodales
/v1/chat/completionsModelos de incrustación de texto
/v1/embeddings -
O utilice la "herramienta de generación de lotes JSONL" anterior para generar un nuevo archivo para tareas formales. Asegúrese de que los campos
modelyurlsean correctos.
2. Modificar el código de Introducción
- Cambie la ruta del archivo de entrada por el nombre de su archivo.
- Configure el parámetro endpoint para que coincida con el campo url en su archivo de entrada.
3. Ejecutar el código y esperar resultados
Cuando la tarea finaliza, los resultados de las solicitudes exitosas se guardan en el archivo local result.jsonl. Si alguna solicitud falló, los detalles del error se guardan en el archivo error.jsonl.
- Resultados exitosos (
output_file_id): Cada línea corresponde a una solicitud exitosa e incluye elcustom_idy laresponse.
- Detalles de fallos (
error_file_id): Contiene información sobre solicitudes fallidas con números de línea y motivos de error. Consulte Códigos de error para solucionar problemas.
Procedimiento detallado
El flujo de trabajo de la API Batch consta de cuatro pasos: cargar un archivo, crear una tarea, consultar el estado de la tarea y descargar los resultados.
1. Cargar archivo
1. Cargar archivo
file_id.Al cargar un archivo, el parámetropurposedebe serbatch.
file-batch-xxx) se puede reutilizar. Si el contenido de entrada permanece igual, omita la recarga y cree directamente una tarea con el ID existente:client.files.list(purpose="batch") para consultar ID de archivos Batch cargados.- SDK de Python de OpenAI
- SDK de Node.js de OpenAI
- Java (HTTP)
- curl (HTTP)
Ejemplo de solicitud
Ejemplo de respuesta
2. Crear una tarea por lotes
2. Crear una tarea por lotes
- SDK de Python de OpenAI
- SDK de Node.js de OpenAI
- Java (HTTP)
- curl (HTTP)
Ejemplo de solicitud
Parámetros de entrada
Campo | Tipo | Método | Obligatorio | Descripción |
|---|---|---|---|---|
input_file_id | String | Cuerpo | Sí | El ID del archivo de entrada. Utilice el ID de archivo devuelto por la API Preparar y cargar archivo, como |
endpoint | String | Cuerpo | Sí | La ruta de acceso a la API. Debe coincidir con el campo url en el archivo de entrada.
|
completion_window | String | Cuerpo | Sí | Tiempo máximo de espera. Rango: 24h-336h, solo números enteros. Unidades: "h" o "d" (p. ej., "24h" o "14d"). |
metadata | Mapa | Cuerpo | No | Metadatos extendidos para la tarea, especificados como pares clave-valor. |
metadata.ds_name | String | Cuerpo | No | Nombre de la tarea. Ejemplo: Longitud máxima: 100 caracteres. Si se especifica varias veces, el último valor tendrá efecto. |
metadata.ds_description | String | Cuerpo | No | Descripción de la tarea. Ejemplo: Longitud máxima: 200 caracteres. Si se especifica varias veces, el último valor tendrá efecto. |
Ejemplo de respuesta
Parámetros de respuesta
Campo | Tipo | Descripción |
|---|---|---|
id | String | El ID de la tarea por lotes. |
object | String | Valor fijo: |
endpoint | String | La ruta de acceso a la API. |
errors | Mapa | Información de error. |
input_file_id | String | ID del archivo de entrada . |
completion_window | String | Tiempo máximo de espera. Rango: 24h-336h, solo números enteros. Unidades: "h" o "d" (p. ej., "24h" o "14d"). |
status | String | Estado de la tarea: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled. |
output_file_id | String | ID de archivo para resultados de solicitudes exitosas. |
error_file_id | String | ID de archivo para resultados de solicitudes fallidas. |
created_at | Integer | Marca de tiempo Unix (segundos) en la que se creó la tarea. |
in_progress_at | Integer | Marca de tiempo Unix (segundos) en la que la tarea comenzó a procesarse. |
expires_at | Integer | Marca de tiempo Unix (segundos) en la que la tarea comienza a agotar el tiempo de espera. |
finalizing_at | Integer | Marca de tiempo Unix (segundos) en la que la tarea se inició por última vez. |
completed_at | Integer | Marca de tiempo Unix (segundos) en la que se completó la tarea. |
failed_at | Integer | Marca de tiempo Unix (segundos) cuando falló la tarea. |
expired_at | Integer | Marca de tiempo Unix (segundos) en la que expiró la tarea. |
cancelling_at | Integer | Marca de tiempo Unix (segundos) en la que la tarea entró en estado de cancelación. |
cancelled_at | Integer | Marca de tiempo Unix (segundos) en la que se canceló la tarea. |
request_counts | Mapa | Recuentos de solicitudes por estado. |
metadata | Mapa | Metadatos adicionales como pares clave-valor. |
metadata.ds_name | String | Nombre de la tarea. |
metadata.ds_description | String | Descripción de la tarea. |
3. Consultar y gestionar tareas por lotes
3. Consultar y gestionar tareas por lotes
Consultar estado de tarea específica
Consultar estado de tarea específica
- SDK de Python de OpenAI
- SDK de Node.js de OpenAI
- Java (HTTP)
- curl (HTTP)
Ejemplo de solicitud
Ejemplo de respuesta
Una consulta exitosa devuelve información detallada de la tarea por lotes. A continuación se muestra un ejemplo de respuesta para una tarea con estado completado:Campo | Tipo | Descripción |
|---|---|---|
id | String | ID de tarea por lotes. |
status | String | Estado de la tarea. Valores posibles:
|
output_file_id | String | ID del archivo de salida que contiene los resultados exitosos. Generado tras la finalización de la tarea. |
error_file_id | String | ID del archivo de errores que contiene los detalles de las solicitudes fallidas. Generado tras la finalización de la tarea si alguna solicitud falló. |
request_counts | Object | Estadísticas de recuento de solicitudes que contienen totales, completadas y fallidas. |
Consultar lista de tareas
Consultar lista de tareas
batches.list() para recuperar la lista de tareas por lotes. Utilice la paginación para recuperar la lista completa de tareas.- SDK de Python de OpenAI
- SDK de Node.js de OpenAI
- Java (HTTP)
- curl (HTTP)
Ejemplo de solicitud
Parámetros de entrada
Campo | Tipo | Método | Obligatorio | Descripción |
|---|---|---|---|---|
after | String | Consulta | No | Cursor para paginación. Establezca esto en el último ID de tarea de la página anterior. |
limit | Integer | Consulta | No | Número de tareas por página. Rango: [1, 100]. Valor predeterminado: 20. |
ds_name | String | Consulta | No | Coincidencia aproximada por nombre de tarea. |
input_file_ids | String | Consulta | No | Filtrar por ID de archivos. Especifique varios ID separados por comas (hasta 20). |
status | String | Consulta | No | Filtrar por estado de la tarea. Especifique varios estados separados por comas. |
create_after | String | Consulta | No | Filtrar tareas creadas después de esta hora. Formato: |
create_before | String | Consulta | No | Filtrar tareas creadas antes de esta hora. Formato: |
Ejemplo de respuesta
Parámetros de respuesta
Campo | Tipo | Descripción |
|---|---|---|
object | String | Tipo de objeto. Valor fijo: list. |
data | Array | Matriz de objetos de tareas por lotes. Consulte los parámetros de respuesta para crear una tarea por lotes. |
first_id | String | ID de la primera tarea por lotes en la página actual. |
last_id | String | ID de la última tarea por lotes en la página actual. |
has_more | Boolean | Si hay páginas adicionales disponibles. |
Cancelar tarea por lotes
Cancelar tarea por lotes
- SDK de Python de OpenAI
- SDK de Node.js de OpenAI
- Java (HTTP)
- curl (HTTP)
Ejemplo de solicitud
Ejemplo de respuesta
Después de cancelar exitosamente una tarea, la API devuelve información detallada de la tarea por lotes. A continuación se muestra un ejemplo de respuesta para una tarea en estado de cancelación:Después de cancelar una tarea, el estado primero cambia acancellingmientras el sistema espera que se completen las solicitudes actualmente en ejecución. El estado eventualmente cambia acancelled. Los resultados de las solicitudes completadas aún se guardan en el archivo de salida.
4. Descargar archivo de resultados de Batch
4. Descargar archivo de resultados de Batch
file_id comience con file-batch_output.- SDK de Python de OpenAI
- SDK de Node.js de OpenAI
- Java (HTTP)
- curl (HTTP)
content para recuperar el contenido del archivo de resultados de la tarea por lotes y utilice el método write_to_file para guardarlo localmente.Ejemplo de solicitud
Ejemplo de respuesta
Ejemplo de respuesta
Ejemplo de respuesta única:Parámetros de respuesta
Campo | Tipo | Descripción |
|---|---|---|
id | String | El ID de la solicitud. |
custom_id | String | El identificador de solicitud definido por el usuario. |
response | Object | El resultado de la solicitud. |
status_code | Integer | Código de estado HTTP. 200 indica éxito. |
request_id | String | ID único generado por el servidor para esta solicitud. |
completion_tokens | Integer | Número de tokens en la respuesta generada por el modelo. |
prompt_tokens | Integer | Número de tokens en el contenido de entrada ( |
total_tokens | Integer | Número total de tokens utilizados por esta solicitud. |
model | String | Nombre del modelo utilizado para esta solicitud. |
error | Object | El objeto de error. Devuelve |
error.code | String | Información de la línea de error y el motivo. Consulte Códigos de error para solucionar problemas. |
error.message | String | Mensaje de error. |
Funciones avanzadas
Configurar notificaciones de finalización
Para tareas de larga duración, utilice notificaciones asíncronas en lugar de sondeo para reducir el consumo de recursos.
- Callback: Especifique una URL accesible públicamente al crear la tarea.
- Cola de mensajes EventBridge: Profundamente integrada con el ecosistema de Alibaba Cloud. No requiere IP pública.
Método 1: Callback
Método 1: Callback
metadata. Una vez completada la tarea, el sistema envía una solicitud POST que contiene el estado de la tarea a la URL especificada:- SDK de Python de OpenAI
- curl (HTTP)
Método 2: Cola de mensajes de EventBridge
Método 2: Cola de mensajes de EventBridge
- Origen del evento (Source):
acs.dashscope - Tipo de evento (Type):
dashscope:System:BatchTaskFinish
Puesta en marcha
-
Gestión de archivos
- Elimine periódicamente los archivos innecesarios utilizando la API de eliminación de archivos de OpenAI para evitar alcanzar los límites de almacenamiento (10,000 archivos o 100 GB).
- Almacene archivos grandes en OSS en lugar de cargarlos directamente.
-
Monitoreo de tareas
- Utilice notificaciones asíncronas de Callback o EventBridge.
- Si se requiere sondeo, establezca el intervalo en más de 1 minuto y utilice una estrategia de retroceso exponencial.
-
Manejo de errores
- Implemente el manejo de errores de red, errores de API y otras excepciones.
- Descargue y analice los detalles de error desde
error_file_id. - Para códigos de error comunes, consulte Códigos de error.
-
Optimización de costos
- Consolidar tareas pequeñas en un solo lote.
- Configure
completion_windowadecuadamente para permitir una mayor flexibilidad de programación.
Herramientas de utilidad
CSV a JSONL
CSV a JSONL
Para personalizar la ruta del archivo u otros parámetros, modifique el código según sea necesario.
Resultados JSONL a CSV
Resultados JSONL a CSV
result.jsonl en result.csv para su análisis en Excel.Para personalizar la ruta del archivo u otros parámetros, modifique el código según sea necesario.
- Utilice un editor de texto (como Sublime Text) para convertir la codificación del archivo CSV a GBK y luego ábralo en Excel.
- Alternativamente, cree un nuevo archivo de Excel y especifique la codificación UTF-8 al importar los datos.
Límites de tasa
API | Límite de tasa (por cuenta de Alibaba Cloud) |
|---|---|
Crear tarea | 1,000 llamadas/minuto; hasta 1,000 tareas simultáneas |
Consultar tarea | 1,000 llamadas/minuto |
Consultar lista de tareas | 100 llamadas/minuto |
Cancelar tarea | 1,000 llamadas/minuto |
Facturación
- Precio unitario: Los tokens de entrada y salida de todas las solicitudes exitosas se cobran al 50% del precio de inferencia en tiempo real para el modelo correspondiente. Para más información, consulte Lista de modelos.
-
Ámbito de facturación:
- Solo se facturan las solicitudes ejecutadas correctamente dentro de una tarea.
- Las solicitudes que fallan debido a errores de análisis de archivos, fallos en la ejecución de tareas o errores a nivel de fila no generan cargos.
- Para tareas canceladas, las solicitudes completadas exitosamente antes de la cancelación se facturan normalmente.
- La inferencia por lotes es un elemento de facturación separado. Admite el Plan de ahorros de propósito general de IA, pero no descuentos, como suscripción (otros planes de ahorros) o cuotas gratuitas para nuevos usuarios. Tampoco admite funciones como caché de contexto.
- Algunos modelos, como qwen3.5-plus y qwen3.5-flash, tienen el modo de pensamiento habilitado de forma predeterminada. Este modo genera tokens de pensamiento adicionales, que se facturan al precio de tokens de salida y aumentan los costos. Para controlar los costos, establezca el parámetro
enable_thinkingsegún la complejidad de la tarea. Para más información, consulte Pensamiento profundo.
Códigos de error
Si una solicitud falla y devuelve un mensaje de error, consulte Códigos de error para obtener una solución.
FAQ
- ¿Cómo elijo entre Batch Chat y Batch File? Utilice Batch File cuando necesite procesar asincrónicamente un archivo grande que contenga muchas solicitudes. Utilice Batch Chat cuando su lógica de negocio requiera enviar sincrónicamente muchas solicitudes de conversación independientes con alta concurrencia.
- ¿Cómo se factura la API Batch File? ¿Necesito comprar un paquete separado? Batch utiliza facturación de pago por uso basada en los tokens consumidos por las solicitudes exitosas. No se requiere un paquete de recursos separado.
- ¿Los archivos por lotes enviados se ejecutan en orden? No. El sistema utiliza programación dinámica basada en la carga de cómputo y no garantiza el orden de ejecución. Las tareas pueden retrasarse cuando los recursos son limitados.
- ¿Cuánto tiempo tarda en completarse un archivo por lotes enviado? El tiempo de ejecución depende de los recursos del sistema y la escala de la tarea. Si una tarea no se completa dentro del completion_window, caduca. Las solicitudes no procesadas en tareas caducadas no se ejecutan y no generan cargos. Recomendaciones de escenario: Utilice llamadas en tiempo real para escenarios que requieren inferencia de modelos estrictamente en tiempo real. Utilice llamadas por lotes para escenarios de procesamiento de datos a gran escala que pueden tolerar retrasos.