Guide de démarrage rapide de l'API Hy3 pour les workflows agentiques et long-contexte

Le Hy3 de Tencent est disponible sur Novita AI avec l’ID de modèle tencent/hy3, un point de terminaison chat/completions compatible OpenAI, une fenêtre de contexte de 256K et la prise en charge de l’appel de fonctions, des sorties structurées et de trois modes de raisonnement. Ce guide de démarrage rapide couvre la configuration développeur : configurez votre client, envoyez votre première requête, utilisez l’appel de fonctions, activez le raisonnement et comprenez les limites de débit avant de développer.

Quand utiliser ce guide de démarrage rapide

Utilisez ce guide lorsque vous avez besoin d’une requête fonctionnelle vers Hy3 avant d’écrire du code supplémentaire. Il couvre un parcours pratique : choisissez l’ID du modèle, authentifiez-vous, envoyez une requête de test, puis étendez à l’appel de fonctions ou au raisonnement selon les besoins de votre charge de travail.

L’architecture de Hy3 — 295B au total, 21B actifs en MoE — est conçue pour équilibrer qualité et efficacité à grande échelle. Il est pertinent d’y recourir lorsque vous avez besoin de :

• Traitement de documents longs (la fenêtre de 256K correspond à environ 200 000 mots en un seul appel).
• Dialogue multitour qui bénéficie d’un large budget de paramètres actifs.
• Tâches agentiques où l’appel d’outils et le formatage fiable des arguments sont importants.
• Assistance au codage couvrant de grandes bases de code sans découpage.

Ce guide couvre uniquement le chemin d’intégration API via Novita AI. Il ne couvre pas l’auto-hébergement, le réglage fin ni le portage vers d’autres moteurs d’inférence.

Étape 1 : Obtenir votre clé API Novita

Créez un compte Novita AI et accédez à la section des clés API de votre console. Générez une clé et stockez-la dans une variable d’environnement. Gardez-la hors du code côté client, des bundles frontend et des dépôts publics.

export NOVITA_API_KEY="votre_clé_api"

Si vous utilisez déjà le SDK Python OpenAI ou des clients compatibles OpenAI dans d’autres projets, la configuration ici est la même — changez l’URL de base et le nom du modèle, rien de plus.

Étape 2 : Confirmer l’ID du modèle et le point de terminaison

Ces trois valeurs sont tout ce dont vous avez besoin pour la configuration :

Élément	Valeur
Clé API	Votre clé API Novita AI, stockée comme variable d’environnement
URL de base compatible OpenAI	https://api.novita.ai/openai
Point de terminaison Chat Completions	POST https://api.novita.ai/openai/v1/chat/completions
ID du modèle	tencent/hy3

Utilisez tencent/hy3 dans tous les appels API. Dans l’interface utilisateur ou la documentation, utilisez le nom d’affichage « Hy3 ».

L’index de documentation Novita AI répertorie l’URL de base compatible OpenAI, et la référence de l’API Chat Completions documente la forme complète de la requête et de la réponse.

Étape 3 : Vérifier la tarification, les limites et les détails du modèle

Valeurs actuelles issues de la page du modèle Hy3 sur Novita AI :

Champ	Valeur
Nom d’affichage	Hy3
ID du modèle API	tencent/hy3
Série de modèles	Hunyuan
Architecture	MoE, 295B total / 21B actifs
Point de terminaison	chat/completions
Modalités d’entrée	Texte
Modalités de sortie	Texte
Fenêtre de contexte	262 144 tokens
Nombre maximal de tokens en sortie	262 144 tokens
Fonctionnalités	Serverless, appel de fonctions, sorties structurées, raisonnement
Prix d’entrée	Indiqué à 0 $ / M tokens (vérifiez le tarif actuel sur la page du modèle)
Prix de sortie	Indiqué à 0 $ / M tokens (vérifiez le tarif actuel sur la page du modèle)

Les limites de débit évoluent selon le niveau du compte (T1–T5) et sont mesurées en requêtes par minute (RPM) et en tokens par minute (TPM). Les seuils et limites actuels des niveaux sont répertoriés dans la documentation sur les limites de débit de Novita AI.

Les prix et les limites de débit peuvent changer. Vérifiez la page du modèle Hy3 et la page de tarification Novita AI avant de vous engager sur une estimation de coût.

Étape 4 : Envoyer votre première requête

Commencez par une simple requête textuelle pour confirmer l’authentification, le routage du modèle et l’analyse de la réponse. Gardez l’invite courte pour tester la connectivité, pas la qualité de la sortie.

Exemple avec 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": "Vous êtes un assistant technique concis."
      },
      {
        "role": "user",
        "content": "Décrivez le principal compromis entre les architectures MoE et les transformeurs denses en trois phrases."
      }
    ],
    "max_tokens": 256,
    "temperature": 0.3
  }'

Une réponse réussie renvoie la forme standard de Chat Completions : un tableau choices, un message avec content, des métadonnées de modèle et de création, et un objet usage avec les nombres de tokens d’invite, de complétion et total.

Utilisez ce test de base pour vérifier :

• Que la clé API est valide et que l’en-tête d’autorisation est correctement formaté.
• Que l’ID de modèle tencent/hy3 est accepté sans erreur 404 ou modèle introuvable.
• Que votre client peut analyser choices[0].message.content.
• Que l’utilisation des tokens est enregistrée afin de pouvoir surveiller les coûts dès la première requête.

Exemple Python

Le SDK Python OpenAI fonctionne avec Novita AI lorsque vous définissez l’URL de 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": "Vous êtes un assistant technique concis."},
        {
            "role": "user",
            "content": "Décrivez le principal compromis entre les architectures MoE et les transformeurs denses en trois phrases.",
        },
    ],
    max_tokens=256,
    temperature=0.3,
)

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

Étape 5 : Lire la réponse

La réponse suit le format standard de Chat Completions OpenAI :

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1751000000,
  "model": "tencent/hy3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Les modèles MoE n'activent qu'une fraction de leurs paramètres totaux..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 80,
    "total_tokens": 132
  }
}

Le champ finish_reason vous indique pourquoi la génération s’est arrêtée. stop signifie que le modèle a atteint une fin naturelle. length signifie que max_tokens a été atteint. Si vous voyez length sur des invites courtes, augmentez max_tokens ou réduisez l’invite.

Paramètres clés

Paramètre	Type	Effet
model	string	Doit être tencent/hy3
messages	array	Historique de la conversation. Les rôles system, user et assistant sont pris en charge.
max_tokens	integer	Limite maximale des tokens de sortie. Définissez-le explicitement ; la valeur par défaut peut varier selon le client.
temperature	float (0–2)	Des valeurs plus faibles produisent une sortie plus déterministe. Utilisez 0.1–0.3 pour le code et les tâches factuelles ; 0.7–1.0 pour les sorties créatives ou variées.
top_p	float (0–1)	Alternative à la température pour l’échantillonnage. Évitez de définir les deux à la fois.
stream	boolean	Mettez true pour recevoir les tokens sous forme de flux. Nécessite la gestion des événements serveur côté client.
tools	array	Définitions d’outils pour l’appel de fonctions. Voir la section sur l’appel de fonctions ci-dessous.
tool_choice	string ou object	Contrôle quel outil le modèle appelle. "auto" laisse le modèle décider.

Pour les charges de travail long-contexte, Hy3 prend en charge jusqu’à 262 144 tokens d’entrée. Budgetisez l’utilisation des tokens par appel et surveillez le coût cumulé si vous traitez de grands documents ou de longs historiques de conversation.

Appel de fonctions

Hy3 prend en charge l’appel de fonctions via le paramètre tools. Utilisez-le lorsque vous souhaitez que le modèle renvoie des arguments structurés plutôt que du texte — pour acheminer une requête vers une action spécifique, analyser une entrée utilisateur en champs typés ou piloter un workflow en plusieurs étapes.

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": "rechercher_base_connaissances",
            "description": "Rechercher dans une base de connaissances produit des réponses aux questions des clients.",
            "parameters": {
                "type": "object",
                "properties": {
                    "requete": {
                        "type": "string",
                        "description": "La question du client ou le sujet à rechercher.",
                    },
                    "max_resultats": {
                        "type": "integer",
                        "description": "Nombre maximum de résultats à renvoyer. La valeur par défaut est 5.",
                    },
                },
                "required": ["requete"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "Vous êtes un assistant de support client. Utilisez l'outil de recherche pour trouver des réponses pertinentes."},
        {
            "role": "user",
            "content": "Quelle est votre politique de retour pour les appareils électroniques achetés au cours des 30 derniers jours ?",
        },
    ],
    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"Outil : {call.function.name}")
        args = json.loads(call.function.arguments)
        print(f"Arguments : {args}")
else:
    print(message.content)

Lorsque le modèle renvoie un appel d’outil, votre application exécute la fonction, puis renvoie le résultat dans la conversation :

# Après avoir exécuté votre fonction de recherche, renvoyez le résultat
resultat_outil = "Retours acceptés dans les 30 jours avec le reçu original. Les appareils électroniques doivent être non ouverts."

suivi = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "Vous êtes un assistant de support client."},
        {"role": "user", "content": "Quelle est votre politique de retour pour les appareils électroniques achetés au cours des 30 derniers jours ?"},
        message,  # le message d'appel d'outil de l'assistant
        {
            "role": "tool",
            "tool_call_id": message.tool_calls[0].id,
            "content": resultat_outil,
        },
    ],
    temperature=0.1,
)

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

Testez vos schémas d’outils sur des requêtes représentatives avant d’acheminer le trafic de production. La qualité de l’extraction des arguments de fonction dépend de la clarté avec laquelle vous décrivez chaque paramètre et ses valeurs attendues.

Mode raisonnement

Hy3 liste le raisonnement comme une fonctionnalité prise en charge sur la page du modèle Novita AI. Les modèles capables de raisonnement réfléchissent à un problème avant de produire une réponse finale, ce qui peut améliorer la qualité des sorties sur des problèmes complexes en plusieurs étapes — débogage de code, mathématiques multi-étapes, analyse de longs documents et tâches de planification.

L’API Chat Completions de Novita AI prend en charge des paramètres liés au raisonnement (separate_reasoning, enable_thinking) pour certains modèles. La question de savoir si ces paramètres sont acceptés par tencent/hy3 et le format exact de la requête ne sont pas confirmés dans la documentation actuelle de Novita. Avant d’intégrer le comportement de raisonnement dans un workflow de production avec Hy3, effectuez un appel de test et vérifiez si la réponse inclut un champ reasoning_content dans choices[0].message.

Pour les noms de paramètres vérifiés et les ID de modèle pris en charge, consultez la référence de l’API Chat Completions Novita AI et le guide des modèles de raisonnement.

Utilisation long-contexte

La fenêtre de contexte de 256K de Hy3 est un avantage pratique pour les tâches qui nécessitent de conserver un grand volume de texte en un seul appel. Cas d’utilisation où cela est important :

• Analyse de documents : envoyez un contrat complet, un article de recherche ou un cahier des charges en tant que contexte et posez des questions ciblées sans découpage.
• Revue de code : passez un grand fichier ou plusieurs fichiers connexes et demandez des observations architecturales, des schémas de bugs ou des suggestions de refactorisation.
• Historique de conversation long : les workflows agentiques qui accumulent de nombreux échanges peuvent rester en contexte plus longtemps avant de nécessiter une synthèse ou une troncature.

Pour les appels long-contexte, définissez max_tokens explicitement en fonction de la longueur de sortie attendue. Envoyer 200 000 tokens d’entrée et laisser le budget de tokens de sortie à sa valeur par défaut gaspille le budget de contexte et peut produire des réponses tronquées.

import os
from openai import OpenAI

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

with open("grand_document.txt") as f:
    texte_document = f.read()

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {
            "role": "system",
            "content": "Vous êtes un assistant d'analyse documentaire. Fournissez des réponses spécifiques et référencées.",
        },
        {
            "role": "user",
            "content": f"Voici le document :\n\n{texte_document}\n\nRésumez les obligations et échéances clés de ce document.",
        },
    ],
    max_tokens=1024,
    temperature=0.2,
)

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

Surveillez usage.prompt_tokens dans la réponse pour suivre la consommation de tokens de vos entrées. Pour les charges de travail qui envoient de manière répétée la même invite système ou le même préambule de document, la planification des limites de débit et des coûts dépend du nombre réel de tokens d’invite, pas seulement du nombre de caractères du document.

Dépannage

401 Non autorisé : La clé API est manquante, expirée ou formatée incorrectement. Vérifiez que l’en-tête Authorization indique Bearer <votre_clé> avec un espace et sans caractères supplémentaires.

404 ou modèle introuvable : L’ID du modèle est incorrect. Confirmez que la chaîne exacte tencent/hy3 correspond à l’ID affiché sur la page du modèle Novita AI. Les ID de modèle sont sensibles à la casse.

429 Limite de débit : Vous avez dépassé le nombre de requêtes ou de tokens par minute pour votre niveau. Ajoutez une logique de nouvelle tentative avec backoff exponentiel, ou demandez un niveau supérieur si votre charge de travail l’exige de manière constante.

finish_reason: length : La réponse a été écourtée car elle a atteint max_tokens. Augmentez la valeur de max_tokens si vous avez besoin de sorties plus longues, mais rappelez-vous que les tokens de sortie affectent le coût et la latence.

Première réponse lente : Les déploiements de grands modèles peuvent avoir une brève latence de démarrage à froid sur la première requête. Les requêtes suivantes vers le même point de terminaison sont généralement plus rapides. Si la latence est une exigence stricte, testez le débit à votre niveau de concurrence cible avant le lancement en production.

L’appel d’outil renvoie des arguments inattendus : Révisez votre schéma d’outil. Ajoutez des descriptions plus spécifiques à chaque paramètre, incluez des exemples de valeurs dans le champ description et listez explicitement les champs obligatoires. Testez d’abord avec des schémas simplifiés, puis ajoutez de la complexité.

FAQ

Hy3 est-il disponible sur Novita AI ?

Oui. Novita AI répertorie Hy3 comme LLM Serverless avec l’ID de modèle API tencent/hy3.

Quel est l’ID de modèle correct ?

Utilisez tencent/hy3 dans tous les appels API. Utilisez « Hy3 » dans le texte destiné aux utilisateurs.

Quel point de terminaison dois-je utiliser ?

Utilisez le point de terminaison Chat Completions compatible OpenAI : POST https://api.novita.ai/openai/v1/chat/completions. Définissez l’URL de base sur https://api.novita.ai/openai lorsque vous utilisez le SDK OpenAI.

Quelle est la taille de la fenêtre de contexte ?

Hy3 prend en charge une fenêtre de contexte de 262 144 tokens et jusqu’à 262 144 tokens de sortie, comme indiqué sur la page du modèle Novita AI.

Hy3 prend-il en charge l’appel de fonctions ?

Oui. Hy3 prend en charge l’appel de fonctions via le paramètre tools dans la requête Chat Completions. Novita liste l’appel de fonctions et les sorties structurées comme fonctionnalités prises en charge.

Hy3 prend-il en charge le raisonnement ?

Le raisonnement est répertorié comme une fonctionnalité sur la page du modèle Novita AI. Les paramètres de requête spécifiques pour activer le raisonnement avec tencent/hy3 ne sont pas confirmés dans la documentation actuelle de Novita. Consultez la référence de l’API Chat Completions Novita AI et effectuez un appel de test pour vérifier le format des paramètres avant d’intégrer le comportement de raisonnement en production.

Quelles entrées Hy3 accepte-t-il ?

Hy3 accepte uniquement les entrées textuelles. Il ne répertorie pas les modalités image ou vidéo sur la page du modèle Novita AI.

Quelle est l’architecture de Hy3 ?

Hy3 utilise une architecture MoE (Mixture of Experts) avec 295B paramètres totaux et 21B paramètres actifs par passage avant. Cela lui permet de traiter des requêtes long-contexte à un coût de calcul inférieur par rapport aux modèles denses de qualité similaire.

Comment obtenir une limite de débit plus élevée ?

Les limites de débit évoluent selon le niveau du compte. Les seuils et limites actuels des niveaux sont répertoriés dans la documentation sur les limites de débit de Novita AI. Contactez le support Novita AI pour les options de mise à niveau.

Articles recommandés

• Appel de fonctions et sorties structurées sur Novita AI
• Comment développer un workflow agentique de recherche approfondie avec LangChain et l’API LLM de Novita AI
• API Hunyuan Image 3 sur Novita AI : Guide de génération texte-à-image