Guide de l'API Hy3 : raisonnement, appels d'outils et long contexte

Hy3 est un modèle MoE en texte uniquement pour le codage, le raisonnement, le travail sur long contexte et les agents. Pour une première intégration, utilisez un endpoint hébergé compatible OpenAI, envoyez une requête Chat Completions normale et évaluez le seul workflow que vous automatiseriez réellement. Ne le standardisez pas tant qu’il ne respecte pas votre schéma d’outils et qu’il ne conserve pas les contraintes qui comptent dans vos longues entrées.

Les détails du fournisseur ci-dessous ont été vérifiés le 14 juillet 2026. DeepInfra documente le modèle sous le nom tencent/Hy3 sur son point de terminaison Chat Completions compatible OpenAI. SiliconFlow répertorie également Hy3 sous le même identifiant de modèle. Les prix, limites et alias du fournisseur peuvent changer, alors vérifiez la page active du fournisseur avant de déployer.

Commencez par un appel API Hy3 hébergé

DeepInfra publie cette requête minimale pour son point de terminaison Hy3 hébergé. Remplacez le jeton par votre propre jeton de fournisseur ; ne le mettez pas dans le code du navigateur ni dans une application cliente.

curl "https://api.deepinfra.com/v1/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPINFRA_TOKEN" \
  -d '{
    "model": "tencent/Hy3",
    "messages": [
      {"role": "user", "content": "Retournez trois vérifications d'acceptation API."}
    ]
  }'

La réponse utilise la structure standard de Chat Completions. Analysez la réponse et les champs de facturation comme ceci :

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "tencent/Hy3",
  "choices": [{
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Lisez choices[0].message.content pour la réponse et usage pour le suivi des jetons. Ajoutez "stream": true uniquement après qu’une requête sans streaming fonctionne ; DeepInfra documente le streaming comme des événements envoyés par le serveur qui se terminent par [DONE].

Les choix de fournisseurs dans le tableau sont volontairement restreints. Il s’agit de routes d’accès public vérifiées, et non d’un classement par prix.

L'annonce de sortie de Tencent du 6 juillet 2026 a présenté Hy3 comme un modèle Mixture-of-Experts à poids ouverts. Son annonce officielle de tarification et sa fiche modèle en font un candidat pour une évaluation hébergée, mais une page d'API ne constitue pas une preuve qu'il convient à une charge de travail de production.

Ce qu'est Hy3, et ce qu'il n'est pas

Hy3 est un modèle MoE de 295B de paramètres avec 21B de paramètres actifs par token. La fiche modèle officielle Hy3 indique 192 experts avec un routage top-8, un backbone à 80 couches, une couche MTP, une fenêtre de contexte de 256K tokens et une licence Apache 2.0.

Ces chiffres décrivent un modèle de texte conçu pour le raisonnement, le codage, les conversations de longue durée et les agents utilisant des outils. Ils ne font pas de Hy3 un modèle d’image ou d’OCR. Un workflow dont l’entrée clé est une facture numérisée, une capture d’écran, une photo de produit ou un graphique a besoin d’un modèle de vision ou d’OCR avant d’avoir besoin de Hy3. Garder cette limite claire évite une erreur d’architecture courante : demander à un modèle de texte performant de récupérer des informations qu’il n’a jamais reçues.

Tencent positionne Hy3 pour le codage, le travail de bureau, la modélisation financière, le travail frontend et le développement de jeux. Considérez-les comme des charges de travail candidates, et non comme un classement universel.

Lisez les affirmations de référence avec leurs limites

L'annonce de publication de Tencent indique une évaluation à l'aveugle menée auprès de 270 experts effectuant des tâches professionnelles, dans laquelle Hy3 a obtenu 2,67 sur 4 et GLM-5.1 a obtenu 2,51 sur 4. La même source précise que l'exactitude de Hy3 sur SWE-Bench Verified variait de moins de quatre points de pourcentage entre les environnements CodeBuddy, Cline et KiloCode. Il s'agit de résultats rapportés par Tencent, et non d'une garantie indépendante que Hy3 battra un rival nommé dans votre environnement.

Artificial Analysis est un autre point de référence pour les mesures au niveau du modèle. Considérez les chiffres de benchmark comme des éléments d’entrée pour la sélection du modèle, et non comme un substitut aux critères d’acceptation au niveau de l’application.

Choisissez le mode de raisonnement en fonction du coût de l’échec

Hy3 expose no_think, low et high d’effort de raisonnement dans ses exemples officiels de mise en service. Le choix doit suivre le coût d’une réponse incorrecte, et non le prestige d’utiliser un modèle de raisonnement.

Conservez no-think pour le travail à portée limitée

no_think est le mode de réponse directe par défaut. C’est la base appropriée lorsque la source est déjà structurée, que la réponse a une forme connue, et qu’une réponse plus lente n’ajouterait pas de raisonnement utile. Par exemple, un flux de support qui choisit un statut documenté et appelle une fonction doit d’abord être testé dans ce mode. Ajoutez un schéma JSON strict et rejetez les réponses qui comportent des champs supplémentaires, au lieu d’espérer qu’une chaîne de raisonnement plus longue corrigera un contrat vague.

Utilisez un raisonnement faible ou élevé lorsqu’une erreur modifie l’action suivante

Passez à low lorsque le modèle doit concilier plusieurs règles ou apporter une modification limitée au code. Réservez high aux tâches où une décision intermédiaire faible entraîne une reprise coûteuse : diagnostiquer un échec à travers des fichiers, choisir un ordre d'opérations ou vérifier des calculs avant un appel d'outil.

Le compromis est mesurable. Comparez la tâche accomplie dans son ensemble : latence des requêtes, nombre de tokens en sortie, tentatives répétées d’appel d’outil, échecs de test et minutes qu’un relecteur passe à corriger la réponse. Un mode qui paraît plus réfléchi mais qui double le nombre de tokens sans réduire le temps de relecture n’est pas le meilleur paramètre de production.

Exécutez un essai API en quatre parties avant d’adopter Hy3

Cet essai crée des preuves pour votre système plutôt qu’un verdict générique sur le modèle. Utilisez des tâches réelles mais non sensibles. Geler les prompts, les schémas et les critères de réussite avant d’exécuter les modèles afin de ne pas déplacer les objectifs après avoir lu une réponse.

Prouvez le chemin de requête avec un appel minimal auto-hébergé

L'exemple suivant suit le modèle officiel de service auto-hébergé compatible OpenAI de Hy3. Il utilise un point de terminaison local compatible vLLM et le nom de modèle configuré par ce serveur. Les IDs de modèles hébergés dépendent du fournisseur ; utilisez le tableau des fournisseurs ci-dessus pour les IDs hébergés vérifiés.

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="EMPTY",
)

response = client.chat.completions.create(
    model="hy3",
    messages=[
        {"role": "user", "content": "Listez les contrôles d'acceptation pour un appel d'outil JSON."}
    ],
    temperature=0.9,
    top_p=1.0,
    extra_body={
        "chat_template_kwargs": {"reasoning_effort": "low"}
    },
)

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

Faites fonctionner cet appel trivial avant d’évaluer un agent complexe. Cela permet de distinguer un problème d’authentification, de point de terminaison, de modèle ou de nom de modèle d’un problème de qualité du modèle. Consignez le fournisseur, la révision du modèle si elle est disponible, le mode de raisonnement, l’horodatage, les jetons d’entrée, les jetons de sortie et le temps écoulé pour chaque essai.

Testez la sortie structurée et les appels d’outils avec votre schéma réel

L’appel d’outils ne doit pas être noté comme « le modèle a choisi une action plausible ». Envoyez un schéma explicite et validez les arguments retournés dans votre application. Il s’agit d’un fragment de requête de type OpenAI ; confirmez la prise en charge exacte des paramètres d’outil auprès du fournisseur avant de vous y fier.

{
  "model": "tencent/Hy3",
  "messages": [
    {"role": "user", "content": "Vérifie le statut de l’incident INC-1042."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_incident",
        "description": "Recherche un incident par son identifiant.",
        "parameters": {
          "type": "object",
          "properties": {"incident_id": {"type": "string"}},
          "required": ["incident_id"],
          "additionalProperties": false
        }
      }
    }
  ]
}

Pour cette demande, une décision d’outil correcte signifie un appel get_incident dont le incident_id est exactement INC-1042. Votre code doit rejeter un champ manquant, une chaîne d’argument JSON mal formée ou un outil inattendu avant d’interagir avec le système en aval. Inspectez cinq éléments :

1. L’outil sélectionné est autorisé pour la tâche.

2. Chaque argument requis est présent et correctement typé.

3. Les identifiants, les dates et les montants proviennent du contexte fourni plutôt que d’être inventés.

4. Le modèle demande une valeur requise manquante plutôt que de la deviner.

5. Une erreur d’outil conduit à une correction bornée ou à un chemin d’escalade, et non à une boucle.

Exécutez suffisamment d’exemples pour inclure des entrées valides, des demandes ambiguës, des champs manquants et une réponse d’outil échouant délibérément. Un JSON fiable dans le cas nominal est utile ; un comportement fiable lorsque le système rejette un argument est ce qui empêche un agent de créer du travail pour un opérateur.

Tester le contexte long pour la rétention des contraintes, pas la longueur du titre

Le contexte 256K de Hy3 n’est utile que lorsque les faits pertinents survivent dans votre format de prompt. Élaborez un test à partir d’un dépôt représentatif, d’un ensemble de politiques ou d’un fil d’historique client. Placez plusieurs contraintes spécifiques à différents endroits, ajoutez des éléments distracteurs réalistes, et demandez une réponse qui doit citer ou transformer ces contraintes.

Évaluez la récupération exacte, le respect de chaque contrainte nommée, les affirmations non prises en charge et le coût total de la requête. Puis recommencez avec votre couche de récupération de production activée. Cela permet de déterminer si un échec relève du modèle, du découpage en chunks, du classement de récupération ou du code d’assemblage du prompt. Faire passer un seul grand document collé n’est pas une preuve suffisante pour désactiver les garde-fous.

Testez la charge de travail qui justifierait une migration

Choisissez une tâche où un meilleur résultat du modèle a une valeur commerciale claire : réparer un test en échec dans plusieurs fichiers, extraire des obligations d’une longue politique, ou mener à bien une opération interne en plusieurs étapes avec des outils. Comparez le flux de production actuel et Hy3 sous le même délai d’attente et la même règle de révision.

Enregistrez le taux de tâches terminées, la latence p50 et p95, les jetons d’entrée et de sortie, le nombre de tentatives d’outils, et le temps de correction du réviseur. C’est aussi là que les retours mixtes de la communauté deviennent utiles. Ne concluez pas, sur la base d’une affirmation, que Hy3 est exceptionnel ou décevant en théorie. Décidez en fonction de la tâche que vous seriez réellement prêt à payer pour automatiser.

API hébergée ou auto-hébergement ?

Utilisez d’abord une API hébergée lorsque vous évaluez le modèle, que le trafic reste incertain ou que votre équipe ne dispose pas déjà de la capacité GPU nécessaire. Cela raccourcit le chemin vers les tests ci-dessus et maintient la disponibilité du fournisseur séparée de la logique de votre application.

N’auto-hébergez que lorsque vous avez une raison concrète de contrôle, de confidentialité, de volume ou de latence, ainsi que l’infrastructure pour le soutenir. La fiche de modèle officielle recommande huit GPU H20-3e ou d’autres GPU à grande mémoire pour servir Hy3, avec des recettes vLLM ou SGLang. Il s’agit de la recommandation de Tencent pour la mise en production, et non d’une affirmation selon laquelle un ordinateur portable grand public fournirait un déploiement équivalent. Mesurez le coût des réservations de GPU, des mises à niveau, de la supervision, du batching et de la responsabilité d’astreinte par rapport à la facture de l’hébergeur avant de considérer les poids ouverts comme une infrastructure gratuite.

Les prix et la disponibilité peuvent changer plus vite que les poids

Tencent a publié la tarification de l'API Hy3 à 1 RMB par million de jetons d'entrée, 4 RMB par million de jetons de sortie, et 0,25 RMB par million de jetons d'entrée mis en cache le 6 juillet. Utilisez cela comme point de référence daté, puis confirmez le prix réel de l'endpoint avant de déployer. Le niveau gratuit d'un fournisseur, le crédit d'introduction ou un alias de modèle gratuit temporaire constituent une disponibilité pour une expérience, et non une promesse permanente de coût unitaire.

Pour une simple estimation des coûts, 100 requêtes quotidiennes contenant 20K tokens d’entrée et 1K tokens de sortie utilisent 2M tokens d’entrée et 0.1M tokens de sortie. Au prix de référence publié par Tencent, cela représente 2.4 RMB par jour, soit environ 72 RMB pour 30 jours. Si les 2M tokens d’entrée remplissent tous les conditions pour une tarification mise en cache, le même calcul donne 0.9 RMB par jour. Il s’agit d’une estimation basée uniquement sur les tokens : elle exclut la marge du fournisseur, les limites du niveau gratuit, les nouvelles tentatives et tout contexte ajouté par votre application.

Lors de l’établissement du budget d’un essai, incluez le contexte récupéré, le prompt système, les définitions d’outils, les tentatives répétées et la sortie produite par le paramètre de raisonnement choisi. Ne choisissez pas Hy3 lorsque l’entrée clé est visuelle, qu’un déploiement local léger est une exigence absolue, ou que l’application ne peut pas valider les arguments d’outil et les effets secondaires en aval.

Pour un agent riche en texte qui a besoin d’une grande fenêtre de contexte, d’un raisonnement configurable et de poids ouverts, Hy3 est un modèle raisonnable à évaluer. Ne le conservez que lorsqu’il réduit le temps de correction à un coût total acceptable.

FAQ

Hy3 est-il multimodal ?

Non. Hy3 est un modèle de saisie de texte et de sortie de texte. Utilisez un modèle de vision ou de OCR lorsque la tâche commence par des images, des numérisations ou des captures d’écran.

Qu'est-ce que la fenêtre de contexte Hy3 ?

La fiche modèle de Tencent indique une fenêtre de contexte de 256K tokens. Une limite de contexte longue ne garantit pas que les faits pertinents seront récupérés ou suivis, alors validez-la avec du contenu source représentatif.

Avec quel mode de raisonnement Hy3 dois-je commencer ?

Commencez avec no_think pour un travail borné et sensible à la latence. Passez à low ou high uniquement lorsque le coût d’échec de la tâche et l’amélioration mesurée justifient les jetons et le temps supplémentaires.

Puis-je auto-héberger Hy3 ?

Oui. Tencent fournit des conseils de déploiement pour vLLM et SGLang et recommande huit GPU à grande mémoire pour l’inférence. L’auto-hébergement doit relever d’une décision liée à la capacité et aux opérations, et non uniquement à la licence open-weight.

Une API Hy3 gratuite est-elle un plan tarifaire permanent ?

Non. L'accès gratuit dépend du fournisseur et peut prendre fin ou voir ses limites changer. Confirmez les conditions actuelles du fournisseur et le tarif payant avant d'engager un workflow de production.