La API de Qwen la ofrece Alibaba Cloud Model Studio (Bailian), y DashScope es su sistema de interfaces nativo. Model Studio ofrece tanto una interfaz compatible con OpenAI como la interfaz nativa de DashScope. Para la mayoría de los equipos, lo más sencillo es empezar por la interfaz compatible con OpenAI: los SDK, frameworks de agentes y herramientas existentes suelen necesitar solo tres cambios: la clave de API, la Base URL y el nombre del modelo.
El verdadero problema no es «si se puede llamar», sino la región de la Base URL, si el nombre del modelo es válido, cómo se interpreta el streaming y qué parámetros no se pueden copiar tal cual al migrar desde OpenAI. Este artículo pone en marcha la cadena con una solicitud mínima y luego cubre tool calling, diagnóstico de errores y una lista de migración.
Nota: Qwen, Tongyi Qianwen, Alibaba Cloud, Model Studio y DashScope son marcas comerciales o nombres de producto del Grupo Alibaba y sus empresas vinculadas. Este artículo solo tiene fines técnicos y no implica relación de subordinación, agencia ni autorización con el Grupo Alibaba. La Base URL, los nombres de modelo, la longitud de contexto y la facturación pueden cambiar; rigen la documentación oficial de Alibaba Cloud Model Studio y la página de precios de modelos de este sitio.
1. Preparación antes de la integración
Antes de empezar, confirma tres cosas:
- Una API Key utilizable y compatible con la región de destino.
- La Base URL correcta: las direcciones de China continental, del sitio internacional y del gateway no se pueden mezclar.
- Un nombre de modelo realmente disponible hoy; no copies ejemplos de artículos antiguos.
Se recomienda validar primero la autenticación y la red con curl, y después integrar el SDK. Así, si algo falla, es más fácil determinar si el problema es la clave, la dirección o el código.
2. Base URL: primero la región, después el dominio
La ruta de la interfaz compatible con OpenAI es fija: /compatible-mode/v1; para el chat se añade /chat/completions. El dominio depende de la región. Las formas habituales son:
| Escenario | Base URL compatible con OpenAI | Notas |
|---|---|---|
| China continental (Pekín, dominio compartido antiguo) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
Compatible con código antiguo; sigue disponible |
| Singapur (sitio internacional) | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
Cuenta y clave del sitio internacional |
| Virginia (EE. UU.) | https://dashscope-us.aliyuncs.com/compatible-mode/v1 |
Solo IPv4; capacidades según la documentación |
| Hong Kong de China | https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 |
Región y clave independientes |
| Espacio de trabajo exclusivo | https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 |
Recomendado para producción; mejor rendimiento y aislamiento |
| ZSQH AI Gateway | https://ai.zhongshangqihang.com/v1 |
Entrada unificada para varios modelos |
Hay varios puntos clave. Primero, la API Key está vinculada a la región; una llamada entre regiones suele devolver 401 e invalid_api_key, lo que indica que la clave y la dirección no coinciden, no que la clave haya dejado de ser válida. Segundo, las cuentas de China continental y del sitio internacional son dos sistemas distintos: las claves, la facturación y las listas de modelos no son intercambiables. Tercero, el dominio exclusivo de un espacio de trabajo solo acepta las claves de ese espacio, pero ofrece mejor rendimiento y aislamiento de tráfico, por lo que es adecuado para producción; el dominio compartido antiguo es cómodo para probar rápido entre espacios.
Si el equipo usa varios modelos y no quiere mantener regiones, cuotas y múltiples claves, puede crear una clave unificada en ZSQH AI Gateway y cambiar la Base URL por la dirección de la última fila de la tabla anterior.
3. Cómo elegir el nombre del modelo
La lista de modelos de Model Studio se actualiza con rapidez. Según la página oficial actual de modelos, la sección de generación de texto incluye modelos Qwen como qwen3.8-max, qwen3.7-plus y qwen3.8-flash. Por el nombre se puede entender, a grandes rasgos, que max apunta al máximo de capacidad, plus al equilibrio y flash a baja latencia y costo; la posición concreta y la longitud de contexto se rigen por la documentación oficial de modelos, y los precios cambian, por lo que rige la página de precios de modelos.
Al elegir, no mires solo «el más potente». Para tareas como atención al cliente, clasificación por lotes o moderación de contenido, suele ser más rentable usar un nivel de baja latencia; para análisis de documentos largos o agentes complejos, sube de nivel. Convierte el nombre del modelo en un parámetro de configuración en lugar de fijarlo en el código: los cambios posteriores serán mucho más sencillos.
Hay otras dos trampas frecuentes. Los nombres qwen-max, qwen-plus y similares de tutoriales antiguos pueden haber cambiado; confirma en la lista de modelos de la consola antes de integrar. Si necesitas capacidades de embeddings, usa la serie correspondiente (por ejemplo, qwen3.7-text-embedding), cuyo cuerpo de solicitud no es igual al de la interfaz de chat. Qwen-Audio no admite el protocolo compatible con OpenAI y requiere la interfaz nativa de DashScope.
4. Primera llamada con curl
Prepara primero la variable de entorno para que la clave no aparezca en el historial de comandos:
export DASHSCOPE_API_KEY="your_key_here"
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"messages": [
{"role": "system", "content": "Eres un asistente técnico conciso."},
{"role": "user", "content": "Explica en tres frases qué es un gateway de API."}
],
"temperature": 0.7
}'
Si la respuesta es correcta, revisa tres campos: choices[0].message.content es la respuesta, usage es el consumo de esta llamada y finish_reason indica el motivo de finalización. Si devuelve 401, revisa primero la clave y la región; si devuelve 404 y ModelNotFound, revisa el nombre del modelo y si ese modelo está habilitado en la región.
5. Llamada con el SDK de Python y streaming
El SDK de OpenAI debe ser la versión 1.0 o superior. Al apuntar la Base URL a Model Studio, la forma de llamar es básicamente la misma que con OpenAI:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
stream = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "Escribe una presentación de producto de menos de cien palabras."}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Con el streaming hay que tener en cuenta que el primer chunk puede contener solo información de rol y un content vacío; no supongas que todos los chunks traen texto. Al añadir stream_options={"include_usage": True}, el consumo aparece en el último chunk. En una conexión HTTP directa, la respuesta tiene formato SSE y termina con data: [DONE]. Si el usuario cierra la página, el servidor debe cancelar cuanto antes la solicitud ascendente para evitar seguir generando y facturando.
6. Tool calling y diferencias de parámetros
El tool calling sigue el formato tools y tool_choice de OpenAI. Cuando el modelo devuelve message.tool_calls, hay que analizar el function.arguments de cada llamada como JSON, ejecutar la función local y devolver el resultado como un mensaje con role: "tool". En un flujo de varios turnos, cada solicitud debe incluir tools. En producción hay que validar parámetros y permisos, y controlar los tiempos de espera; no se deben confiar directamente los parámetros generados por el modelo.
La documentación oficial de compatibilidad señala actualmente dos límites para las herramientas: solo algunos modelos las admiten, y tools todavía no se puede usar junto con stream=True. La lista de modelos y sus capacidades se actualiza constantemente; antes de lanzar, prueba con el modelo objetivo. Si el negocio necesita llamar herramientas mientras transmite en streaming, considera la interfaz nativa de DashScope o convierte la llamada de herramientas en un paso sin streaming.
Al migrar desde OpenAI, ten en cuenta estas diferencias de parámetros:
messages: solomessages[0]puede tener el rol system; user y assistant normalmente deben alternarse, y el último mensaje debe ser de user.temperature: el rango es [0, 2); la documentación oficial no recomienda usar 0.top_p: el rango es (0, 1.0).seed: usa un entero sin signo de 64 bits.stop: los elementos del arreglo no pueden mezclar ID de token y cadenas.system_fingerprint: actualmente devuelve una cadena vacía.- Parámetros extendidos como
enable_search: suelen pasarse medianteextra_body, y no todos los modelos los admiten. - Campos como
response_formatyfrequency_penalty: la documentación de compatibilidad no los garantiza; no supongas que se comportan igual que en OpenAI.
7. Tabla de errores frecuentes
| Síntoma | Código habitual | Posible causa | Qué hacer |
|---|---|---|---|
| 401 | InvalidApiKey / invalid_api_key |
Clave incorrecta, región que no coincide, mezcla de clave de paquete | Verifica la región y el tipo de clave frente a la Base URL |
| 404 | ModelNotFound / model_not_found |
Nombre mal escrito, modelo inexistente en la región, modelo no habilitado | Consulta la lista de modelos de la consola |
| 404 | model_not_supported |
El modelo no admite el modo compatible con OpenAI | Usa la interfaz nativa de DashScope |
| 403 | AccessDenied / Workspace.AccessDenied |
Permisos insuficientes de espacio o modelo | Revisa la autorización del espacio de trabajo |
| 403 | AllocationQuota.FreeTierOnly |
Cuota gratuita agotada | Recarga o ajusta el plan |
| 429 | Familia Throttling |
Frecuencia de solicitudes, tokens o concurrencia por encima del límite | Reduce la concurrencia, aplica retroceso y solicita cuota |
| 400 | Arrearage |
Cuenta con impago | Recarga y vuelve a intentar |
| 400 | Range of input length... |
La entrada supera el límite de contexto | Comprime el prompt o divide en segmentos |
| 400 | DataInspectionFailed |
Entrada o salida bloqueada por seguridad de contenido | Ajusta el contenido y vuelve a intentar |
Reintentar solo sirve para 429, 5xx y tiempos de espera de red. Un 401, 403, 404 o un error de parámetros no mejora al reintentar; solo desperdicia tiempo y cuota. Al diagnosticar, registra el Request ID de la respuesta y búscalo en los registros de la consola; es mucho más rápido que adivinar.
8. Lista de verificación para migrar desde OpenAI
- Haz una copia de seguridad de los prompts, parámetros de modelo y conjuntos de evaluación actuales.
- Crea una clave Qwen compatible con la región de destino; no reutilices claves de otro proveedor.
- Convierte la Base URL y el nombre del modelo en parámetros de configuración.
- Revisa las reglas de roles de
messages: primer mensaje system y último user. - Revisa el análisis del streaming y la forma de contabilizar el uso.
- Haz una prueba de regresión de tool calling con herramientas reales.
- Compara calidad de salida, latencia y consumo con el mismo lote de muestras.
- Ajusta reintentos, tiempos de espera y concurrencia; observa durante una semana antes de pasar todo el tráfico.
- Registra el Request ID en los logs y mantén un interruptor de reversión.
9. Preguntas frecuentes (FAQ)
1. ¿La API de Qwen es compatible con OpenAI?
La mayoría de las interfaces de chat habituales lo son, pero persisten diferencias como el vínculo con la región, el orden de los roles, los rangos de parámetros y los límites de tool calling. Verifica cada punto con la documentación oficial de compatibilidad con OpenAI; no supongas que todos los parámetros se comportan igual.
2. ¿Se puede usar la misma clave en China continental y en el sitio internacional?
No. Las cuentas, claves, dominios de acceso y facturación de los dos sitios son independientes. Una llamada entre regiones o sitios suele devolver 401 e invalid_api_key.
3. ¿Conviene usar el dominio antiguo o el dominio exclusivo del espacio de trabajo?
Para pruebas rápidas sirve el dominio compartido antiguo; para producción se recomienda el dominio exclusivo del espacio de trabajo, con mejor rendimiento y aislamiento de tráfico. Lo esencial es que la clave coincida con la región y el espacio de trabajo del dominio.
4. El nombre del modelo es correcto, pero devuelve model_not_found. ¿Por qué?
Las causas habituales son que el modelo no existe en esa región, que no está habilitado, que el nombre tiene mayúsculas y minúsculas distintas o que se accede a una versión retirada. Toma como referencia la lista actual de modelos de la consola.
5. ¿Se pueden usar tools y stream a la vez?
La documentación oficial de compatibilidad indica actualmente que no se pueden usar juntos y que solo algunos modelos admiten tool calling. Las capacidades y límites cambian con las actualizaciones; prueba con el modelo objetivo antes de lanzar o usa la interfaz nativa de DashScope.
