Inicio Rápido de la API Hy3 para Flujos de Trabajo Agénticos y de Contexto Largo

Hy3 de Tencent está disponible en Novita AI con el ID de modelo tencent/hy3, un endpoint chat/completions compatible con OpenAI, una ventana de contexto de 256K y soporte para llamada a funciones, salidas estructuradas y tres modos de razonamiento. Este inicio rápido cubre la configuración para desarrolladores: configura tu cliente, envía tu primera solicitud, usa la llamada a funciones, habilita el razonamiento y comprende los límites de velocidad antes de empezar a construir.

Cuándo Usar Este Inicio Rápido

Usa esta guía cuando necesites una solicitud funcional a Hy3 antes de escribir cualquier código adicional. Cubre un camino práctico: elige el ID del modelo, autentícate, envía una solicitud de prueba y luego extiende a llamada a funciones o razonamiento según las necesidades de tu carga de trabajo.

La arquitectura de Hy3 — un total de 295B, 21B activos MoE — está diseñada para equilibrar calidad y eficiencia a escala. Vale la pena considerarlo cuando necesites:

• Procesamiento de documentos de contexto largo (la ventana de 256K abarca aproximadamente 200,000 palabras en una sola llamada).
• Diálogo multi-turno que se beneficia de un gran presupuesto de parámetros activos.
• Tareas agénticas donde la llamada a herramientas y el formato confiable de argumentos son importantes.
• Asistencia de codificación que abarca grandes bases de código sin necesidad de fragmentación.

Esta guía cubre solo la ruta de integración de API a través de Novita AI. No cubre auto-hospedaje, ajuste fino ni migración a otros backends de inferencia.

Paso 1: Obtén tu Clave de API de Novita

Crea una cuenta en Novita AI y navega a la sección de claves de API de tu consola. Genera una clave y guárdala en una variable de entorno. Mantenla fuera del código del lado del cliente, los bundles del frontend y los repositorios públicos.

export NOVITA_API_KEY="tu_clave_api"

Si ya usas el SDK de Python de OpenAI o clientes compatibles con OpenAI en otros proyectos, la configuración aquí es la misma: cambia la URL base y el nombre del modelo, nada más.

Paso 2: Confirma el ID del Modelo y el Endpoint

Estos tres valores son todo lo que necesitas para la configuración:

Elemento	Valor
Clave de API	Tu clave de API de Novita AI, almacenada como variable de entorno
URL base compatible con OpenAI	https://api.novita.ai/openai
Endpoint de chat completions	POST https://api.novita.ai/openai/v1/chat/completions
ID del modelo	tencent/hy3

Usa tencent/hy3 en todas las llamadas a la API. En la interfaz de usuario o documentación, usa el nombre para mostrar “Hy3”.

El índice de documentación de Novita AI enumera la URL base compatible con OpenAI, y la referencia de la API de chat completions documenta la forma completa de la solicitud y respuesta.

Paso 3: Verifica Precios, Límites y Detalles del Modelo

Valores actuales de la página del modelo Hy3 en Novita AI:

Campo	Valor
Nombre para mostrar	Hy3
ID del modelo de API	tencent/hy3
Serie del modelo	Hunyuan
Arquitectura	MoE, 295B total / 21B activos
Endpoint	chat/completions
Modalidades de entrada	Texto
Modalidades de salida	Texto
Ventana de contexto	262,144 tokens
Máximo de tokens de salida	262,144 tokens
Funcionalidades	Sin servidor, llamada a funciones, salidas estructuradas, razonamiento
Precio de entrada	Listado en $0 / M tokens (verifica la tarifa actual en la página del modelo)
Precio de salida	Listado en $0 / M tokens (verifica la tarifa actual en la página del modelo)

Los límites de velocidad se escalan según el nivel de la cuenta (T1–T5) y se miden en solicitudes por minuto (RPM) y tokens por minuto (TPM). Los umbrales y límites de nivel actuales se enumeran en la documentación de límites de velocidad de Novita AI.

Los precios y los límites de velocidad pueden cambiar. Consulta la página del modelo Hy3 y la página de precios de Novita AI antes de comprometerte con cualquier estimación de costos.

Paso 4: Envía tu Primera Solicitud

Comienza con una solicitud de texto simple para confirmar la autenticación, el enrutamiento del modelo y el análisis de la respuesta. Mantén el mensaje corto para que estés probando la conectividad, no la calidad de la salida.

Ejemplo con cURL

curl "https://api.novita.ai/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${NOVITA_API_KEY}" \
  -d '{
    "model": "tencent/hy3",
    "messages": [
      {
        "role": "system",
        "content": "Eres un asistente técnico conciso."
      },
      {
        "role": "user",
        "content": "Describe la principal compensación entre las arquitecturas MoE y transformer densas en tres oraciones."
      }
    ],
    "max_tokens": 256,
    "temperature": 0.3
  }'

Una respuesta exitosa devuelve la forma estándar de chat completions: un array choices, un mensaje con content, metadatos de modelo y creación, y un objeto usage con los recuentos de tokens de prompt, finalización y totales.

Usa esta prueba de humo para verificar:

• La clave de API es válida y el encabezado de autorización está formateado correctamente.
• El ID del modelo tencent/hy3 es aceptado sin un error 404 o modelo-no-encontrado.
• Tu cliente puede analizar choices[0].message.content.
• El uso de tokens se registra para que puedas monitorear los costos desde la primera solicitud.

Ejemplo en Python

El SDK de Python de OpenAI funciona con Novita AI cuando configuras la URL base:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "Eres un asistente técnico conciso."},
        {
            "role": "user",
            "content": "Describe la principal compensación entre las arquitecturas MoE y transformer densas en tres oraciones.",
        },
    ],
    max_tokens=256,
    temperature=0.3,
)

print(response.choices[0].message.content)
print("Tokens usados:", response.usage.total_tokens)

Paso 5: Lee la Respuesta

La respuesta sigue el formato estándar de chat completions de OpenAI:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1751000000,
  "model": "tencent/hy3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Los modelos MoE activan solo una fracción de sus parámetros totales..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 80,
    "total_tokens": 132
  }
}

El campo finish_reason te indica por qué se detuvo la generación. stop significa que el modelo llegó a un final natural. length significa que se alcanzó max_tokens. Si ves length en mensajes cortos, aumenta max_tokens o reduce el mensaje.

Parámetros Clave

Parámetro	Tipo	Efecto
model	cadena	Debe ser tencent/hy3
messages	array	Historial de conversación. Los roles system, user y assistant son compatibles.
max_tokens	entero	Límite máximo de tokens de salida. Configúralo explícitamente; el valor predeterminado puede variar según el cliente.
temperature	flotante (0–2)	Los valores más bajos producen una salida más determinista. Usa 0.1–0.3 para código y tareas fácticas; 0.7–1.0 para salidas creativas o variadas.
top_p	flotante (0–1)	Alternativa a temperature para el muestreo. Evita configurar ambos a la vez.
stream	booleano	Establécelo en true para recibir tokens como un flujo. Requiere manejo de eventos enviados por el servidor en tu cliente.
tools	array	Definiciones de herramientas para la llamada a funciones. Consulta la sección de llamada a funciones a continuación.
tool_choice	cadena u objeto	Controla qué herramienta llama el modelo. "auto" permite que el modelo decida.

Para cargas de trabajo de contexto largo, Hy3 admite hasta 262,144 tokens de entrada. Presupuesta el uso de tokens por llamada y monitorea el costo acumulativo si estás procesando documentos grandes o historiales de conversación largos.

Llamada a Funciones

Hy3 admite la llamada a funciones a través del parámetro tools. Úsalo cuando quieras que el modelo devuelva argumentos estructurados en lugar de prosa — enrutar una solicitud a una acción específica, analizar la entrada del usuario en campos tipificados o impulsar un flujo de trabajo de varios pasos.

import os
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "buscar_base_conocimiento",
            "description": "Busca en una base de conocimiento de productos respuestas a consultas de clientes.",
            "parameters": {
                "type": "object",
                "properties": {
                    "consulta": {
                        "type": "string",
                        "description": "La pregunta o tema del cliente a buscar.",
                    },
                    "max_resultados": {
                        "type": "integer",
                        "description": "Número máximo de resultados a devolver. El valor predeterminado es 5.",
                    },
                },
                "required": ["consulta"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "Eres un asistente de atención al cliente. Usa la herramienta de búsqueda para encontrar respuestas relevantes."},
        {
            "role": "user",
            "content": "¿Cuál es su política de devolución para productos electrónicos comprados en los últimos 30 días?",
        },
    ],
    tools=tools,
    tool_choice="auto",
    temperature=0.1,
)

message = response.choices[0].message
if message.tool_calls:
    for call in message.tool_calls:
        print(f"Herramienta: {call.function.name}")
        args = json.loads(call.function.arguments)
        print(f"Argumentos: {args}")
else:
    print(message.content)

Cuando el modelo devuelve una llamada a herramienta, tu aplicación ejecuta la función y luego envía el resultado de vuelta a la conversación:

# Después de ejecutar tu función de búsqueda, envía el resultado de vuelta
resultado_herramienta = "Se aceptan devoluciones dentro de los 30 días con el recibo original. Los productos electrónicos deben estar sin abrir."

seguimiento = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "Eres un asistente de atención al cliente."},
        {"role": "user", "content": "¿Cuál es su política de devolución para productos electrónicos comprados en los últimos 30 días?"},
        message,  # el mensaje de llamada a herramienta del asistente
        {
            "role": "tool",
            "tool_call_id": message.tool_calls[0].id,
            "content": resultado_herramienta,
        },
    ],
    temperature=0.1,
)

print(seguimiento.choices[0].message.content)

Prueba tus esquemas de herramientas en consultas representativas antes de enrutar el tráfico de producción. La calidad de la extracción de argumentos de función depende de qué tan claramente describas cada parámetro y sus valores esperados.

Modo de Razonamiento

Hy3 lista el razonamiento como una funcionalidad compatible en la página del modelo de Novita AI. Los modelos con capacidad de razonamiento piensan en un problema antes de producir una respuesta final, lo que puede mejorar la calidad de la salida en problemas complejos de varios pasos: depuración de código, matemáticas de varios pasos, análisis de documentos largos y tareas de planificación.

La API de chat completions de Novita AI admite parámetros relacionados con el razonamiento (separate_reasoning, enable_thinking) para modelos selectos. Si estos parámetros son aceptados por tencent/hy3 y el formato exacto de la solicitud no están confirmados en la documentación actual de Novita. Antes de incorporar el comportamiento de razonamiento en un flujo de trabajo de producción con Hy3, realiza una llamada de prueba y verifica si la respuesta incluye un campo reasoning_content en choices[0].message.

Para nombres de parámetros verificados e IDs de modelo compatibles, consulta la referencia de la API de chat completions de Novita AI y la guía de Modelos de Razonamiento.

Uso de Contexto Largo

La ventana de contexto de 256K de Hy3 es una ventaja práctica para tareas que requieren mantener un gran cuerpo de texto en una sola llamada. Casos de uso donde esto es importante:

• Análisis de documentos: Envía un contrato completo, artículo de investigación o especificación como contexto y haz preguntas específicas sin necesidad de fragmentación.
• Revisión de base de código: Pasa un archivo grande o varios archivos relacionados y solicita observaciones de arquitectura, patrones de errores o sugerencias de refactorización.
• Historial de conversación largo: Los flujos de trabajo agénticos que acumulan muchos turnos pueden permanecer en contexto por más tiempo antes de requerir resumen o truncamiento.

Para llamadas de contexto largo, establece max_tokens explícitamente según la longitud de salida esperada. Enviar 200K tokens de entrada y dejar el presupuesto de tokens de salida en su valor predeterminado desperdicia el presupuesto de contexto y puede producir respuestas truncadas.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

with open("documento_grande.txt") as f:
    texto_documento = f.read()

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {
            "role": "system",
            "content": "Eres un asistente de análisis de documentos. Proporciona respuestas específicas y referenciadas.",
        },
        {
            "role": "user",
            "content": f"Aquí está el documento:\n\n{texto_documento}\n\nResume las obligaciones clave y los plazos en este documento.",
        },
    ],
    max_tokens=1024,
    temperature=0.2,
)

print(response.choices[0].message.content)

Monitorea usage.prompt_tokens en la respuesta para rastrear cuántos tokens consumen tus entradas. Para cargas de trabajo que envían repetidamente el mismo mensaje de sistema o preámbulo de documento, la planificación de límites de velocidad y costos depende del recuento real de tokens de prompt, no solo del recuento de caracteres del documento.

Solución de Problemas

401 No autorizado: La clave de API falta, ha expirado o está formateada incorrectamente. Verifica que el encabezado Authorization lea Bearer <tu_clave> con un espacio y sin caracteres adicionales.

404 o modelo no encontrado: El ID del modelo es incorrecto. Confirma que la cadena exacta tencent/hy3 coincida con el ID que se muestra en la página del modelo de Novita AI. Los IDs de modelo distinguen entre mayúsculas y minúsculas.

429 Límite de velocidad: Has excedido las solicitudes o tokens por minuto para tu nivel. Agrega lógica de reintento con retroceso exponencial, o solicita un nivel superior si tu carga de trabajo lo requiere de manera consistente.

finish_reason: length: La respuesta se truncó porque alcanzó max_tokens. Aumenta el valor de max_tokens si necesitas salidas más largas, pero recuerda que los tokens de salida afectan el costo y la latencia.

Respuesta lenta inicial: Las implementaciones de modelos grandes pueden tener una breve latencia de arranque en frío en la primera solicitud. Las solicitudes posteriores al mismo endpoint suelen ser más rápidas. Si la latencia es un requisito estricto, prueba el rendimiento en tu nivel de concurrencia objetivo antes del lanzamiento a producción.

La llamada a herramienta devuelve argumentos inesperados: Revisa tu esquema de herramienta. Agrega descripciones más específicas a cada parámetro, incluye valores de ejemplo en el campo de descripción y enumera los campos requeridos explícitamente. Prueba primero con esquemas simplificados y luego añade complejidad.

Preguntas Frecuentes

¿Está Hy3 disponible en Novita AI?

Sí. Novita AI lista Hy3 como un LLM sin servidor con el ID de modelo de API tencent/hy3.

¿Cuál es el ID de modelo correcto?

Usa tencent/hy3 en todas las llamadas a la API. Usa “Hy3” en el texto dirigido al usuario.

¿Qué endpoint debo usar?

Usa el endpoint de chat completions compatible con OpenAI: POST https://api.novita.ai/openai/v1/chat/completions. Configura la URL base como https://api.novita.ai/openai cuando uses el SDK de OpenAI.

¿Qué tan grande es la ventana de contexto?

Hy3 admite una ventana de contexto de 262,144 tokens y hasta 262,144 tokens de salida, según se indica en la página del modelo de Novita AI.

¿Hy3 admite llamada a funciones?

Sí. Hy3 admite llamada a funciones a través del parámetro tools en la solicitud de chat completions. Novita lista la llamada a funciones y las salidas estructuradas como funcionalidades compatibles.

¿Hy3 admite razonamiento?

El razonamiento se lista como una funcionalidad en la página del modelo de Novita AI. Los parámetros de solicitud específicos para habilitar el razonamiento con tencent/hy3 no están confirmados en la documentación actual de Novita. Consulta la referencia de la API de chat completions de Novita AI y realiza una llamada de prueba para verificar el formato del parámetro antes de incorporar el comportamiento de razonamiento en producción.

¿Qué entradas acepta Hy3?

Hy3 acepta solo entradas de texto. No lista modalidades de imagen o video en la página del modelo de Novita AI.

¿Cuál es la arquitectura de Hy3?

Hy3 utiliza una arquitectura MoE (Mezcla de Expertos) con 295B parámetros totales y 21B parámetros activos por paso hacia adelante. Esto le permite servir solicitudes de contexto largo a un costo computacional más bajo en comparación con los modelos densos de calidad similar.

¿Cómo obtengo un límite de velocidad más alto?

Los límites de velocidad se escalan según el nivel de la cuenta. Los umbrales y límites de nivel actuales se enumeran en la documentación de límites de velocidad de Novita AI. Contacta al soporte de Novita AI para opciones de actualización.

Artículos Recomendados

• Llamada a Funciones y Salidas Estructuradas en Novita AI
• Cómo Desarrollar un Flujo de Trabajo Agéntico de Búsqueda Profunda con LangChain y la API LLM de Novita AI
• API de Hunyuan Image 3 en Novita AI: Guía de Generación de Texto a Imagen