Guia da API Hy3: raciocínio, chamadas de ferramentas e contexto longo

Hy3 é um modelo MoE somente de texto para programação, raciocínio, trabalho com contexto longo e agentes. Para uma primeira integração, use um endpoint hospedado compatível com OpenAI, envie uma solicitação normal de Chat Completions e avalie o único fluxo de trabalho que você realmente automatizaria. Não padronize seu uso até que ele siga seu esquema de ferramentas e mantenha as restrições que importam em suas entradas longas.

Os detalhes do provedor abaixo foram verificados em 14 de julho de 2026. A documentação da DeepInfra apresenta o modelo como tencent/Hy3 em seu endpoint de Chat Completions compatível com OpenAI. A SiliconFlow também lista o Hy3 sob o mesmo ID de modelo. Os preços, limites e aliases do provedor podem mudar, então confirme a página atual do provedor antes de publicar.

Comece com uma chamada de API Hy3 hospedada

A DeepInfra publica esta solicitação mínima para seu endpoint Hy3 hospedado. Substitua o token pelo seu próprio token de provedor; não o coloque em código do navegador nem em um aplicativo 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": "Retorne três verificações de aceitação da API."}
    ]
  }'

A resposta usa o formato padrão de Chat Completions. Analise os campos de resposta e cobrança assim:

{
  "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
  }
}

Leia choices[0].message.content para a resposta e usage para a contabilização de tokens. Adicione "stream": true somente depois que uma solicitação sem streaming funcionar; a DeepInfra documenta o streaming como eventos enviados pelo servidor que terminam com [DONE].

As opções de provedores na tabela são deliberadamente restritas. Elas são rotas de acesso público verificadas, não uma classificação de preços.

O anúncio de lançamento da Tencent em 6 de julho de 2026 apresentou o Hy3 como um modelo Mixture-of-Experts de pesos abertos. Seu anúncio oficial de preços e o model card o tornam um candidato para uma avaliação hospedada, mas uma página de API não é evidência de que ele atenda a uma carga de trabalho de produção.

O que é Hy3 e o que ele não é

Hy3 é um modelo MoE com 295B de parâmetros e 21B de parâmetros ativos por token. O card oficial do modelo Hy3 lista 192 especialistas com roteamento top-8, uma backbone de 80 camadas, uma camada MTP, uma janela de contexto de 256K tokens e uma licença Apache 2.0.

Esses números descrevem um modelo de texto projetado para raciocínio, codificação, conversas prolongadas e agentes que usam ferramentas. Eles não fazem do Hy3 um modelo de imagem ou OCR. Um fluxo de trabalho cuja entrada principal é uma fatura digitalizada, captura de tela, foto de produto ou gráfico precisa de um modelo de visão ou OCR antes de precisar do Hy3. Manter esse limite claro evita um erro comum de arquitetura: pedir a um modelo de texto capaz que recupere informações que ele nunca recebeu.

A Tencent posiciona o Hy3 para programação, trabalho de escritório, modelagem financeira, trabalho de frontend e desenvolvimento de jogos. Considere esses como cargas de trabalho candidatas, não como um ranking universal.

Leia as alegações do benchmark com suas limitações

O anúncio de lançamento da Tencent relata uma avaliação cega com 270 especialistas realizando tarefas de trabalho, na qual o Hy3 obteve 2,67 de 4 e o GLM-5.1 obteve 2,51 de 4. A mesma fonte diz que a precisão do SWE-Bench Verified do Hy3 variou em menos de quatro pontos percentuais entre os scaffolds CodeBuddy, Cline e KiloCode. Esses são resultados relatados pela Tencent, e não uma garantia independente de que o Hy3 superará um rival específico no seu ambiente.

Artificial Analysis é outro ponto de referência para medições em nível de modelo. Leia os números de benchmark como insumos para a seleção de modelos, não como substitutos para critérios de aceitação em nível de aplicação.

Escolha o modo de raciocínio pelo custo da falha

Hy3 expõe o esforço de raciocínio no_think, low e high em seus exemplos oficiais de serving. A escolha deve seguir o custo de uma resposta incorreta, não o prestígio de usar um modelo de raciocínio.

Mantenha no-think para trabalho limitado

no_think é o modo padrão de resposta direta. É a linha de base adequada quando a fonte já está estruturada, a resposta tem um formato conhecido e uma resposta mais lenta não adicionaria raciocínio útil. Por exemplo, um fluxo de suporte que escolhe um status documentado e chama uma função deve primeiro ser testado neste modo. Adicione um esquema JSON rigoroso e rejeite respostas que tenham campos extras, em vez de esperar que uma cadeia mais longa de raciocínio corrija um contrato vago.

Use raciocínio baixo ou alto quando um erro altera a próxima ação

Mude para low quando o modelo precisar reconciliar várias regras ou fazer uma alteração limitada no código. Reserve high para trabalhos em que uma decisão intermediária fraca cause uma retrabalho caro: diagnosticar uma falha em vários arquivos, escolher uma ordem de operações ou verificar cálculos antes de uma chamada de ferramenta.

A compensação é mensurável. Compare a tarefa concluída como um todo: latência da requisição, contagem de tokens de saída, tentativas de repetição de chamadas de ferramenta, falhas de teste e os minutos que um revisor gasta corrigindo a resposta. Um modo que parece mais cuidadoso, mas dobra o número de tokens sem reduzir o tempo de revisão, não é a melhor configuração para produção.

Execute um teste da API em quatro partes antes de adotar o Hy3

Esta avaliação cria evidências para o seu sistema, em vez de um veredito genérico do modelo. Use tarefas reais, porém não sensíveis. Congele os prompts, esquemas e critérios de aprovação antes de executar os modelos, para que você não mude as regras depois de ler uma resposta.

Prove o caminho da requisição com uma chamada mínima auto-hospedada

O exemplo a seguir segue o padrão oficial de serving self-hosted compatível com OpenAI da Hy3. Ele usa um endpoint local compatível com vLLM e o nome do modelo configurado por esse servidor. Os IDs de modelos hospedados são específicos de cada provedor; use a tabela de provedores acima para os IDs hospedados verificados.

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": "Liste os critérios de aceitação para uma chamada de ferramenta JSON."}
    ],
    temperature=0.9,
    top_p=1.0,
    extra_body={
        "chat_template_kwargs": {"reasoning_effort": "low"}
    },
)

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

Faça esta chamada trivial funcionar antes de avaliar um agente complicado. Isso separa um problema de autenticação, endpoint, template ou nome do modelo de um problema de qualidade do modelo. Registre o provedor, a revisão do modelo, se disponível, o modo de raciocínio, o timestamp, os tokens de entrada, os tokens de saída e o tempo decorrido para cada tentativa.

Teste a saída estruturada e as chamadas de ferramenta com seu esquema real

Tool calling não deve ser avaliado como "o modelo escolheu uma ação plausível." Envie um schema explícito e valide os argumentos retornados em sua aplicação. Este é um fragmento de solicitação no estilo OpenAI; confirme o suporte exato ao parâmetro tool com o provedor antes de depender dele.

{
  "model": "tencent/Hy3",
  "messages": [
    {"role": "user", "content": "Verifique o status do incidente INC-1042."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_incident",
        "description": "Consulte um incidente pelo seu identificador.",
        "parameters": {
          "type": "object",
          "properties": {"incident_id": {"type": "string"}},
          "required": ["incident_id"],
          "additionalProperties": false
        }
      }
    }
  ]
}

Para esta solicitação, uma decisão correta de ferramenta significa uma chamada get_incident cujo incident_id seja exatamente INC-1042. Seu código deve rejeitar um campo ausente, uma string de argumento JSON malformada ou uma ferramenta inesperada antes de tocar no sistema downstream. Inspecione cinco coisas:

1. A ferramenta selecionada é permitida para a tarefa.

2. Todo argumento obrigatório está presente e tipado corretamente.

3. IDs, datas e valores vêm do contexto fornecido em vez de serem inventados.

4. O modelo solicita um valor obrigatório ausente em vez de adivinhá-lo.

5. Um erro da ferramenta leva a um caminho limitado de correção ou escalonamento, não a um loop.

Execute exemplos suficientes para incluir entradas válidas, solicitações ambíguas, campos ausentes e uma resposta de ferramenta propositalmente malsucedida. JSON confiável no caminho feliz é útil; comportamento confiável quando o sistema rejeita um argumento é o que impede um agente de criar trabalho para um operador.

Teste de contexto longo para retenção de restrições, não comprimento de título

O contexto de 256K do Hy3 só é valioso quando os fatos relevantes sobrevivem no formato do seu prompt. Crie um teste a partir de um repositório representativo, um pacote de políticas ou uma thread de histórico de cliente. Coloque várias restrições específicas em locais diferentes, adicione distrações realistas e peça uma resposta que precise citar ou transformar essas restrições.

Pontue a recuperação exata, a aderência a cada restrição nomeada, as alegações não suportadas e o custo total da solicitação. Em seguida, repita com sua camada de recuperação de produção ativada. Isso revela se uma falha pertence ao modelo, à segmentação, à classificação da recuperação ou ao código de montagem do prompt. Passar um único documento grande colado não é evidência suficiente para desativar os guardrails.

Teste a carga de trabalho que justificaria uma migração

Escolha uma tarefa em que um resultado de modelo melhor tenha um valor comercial claro: corrigir um teste com falha em vários arquivos, extrair obrigações de uma política longa ou concluir uma operação interna de várias etapas com ferramentas. Compare o fluxo de produção atual e o Hy3 sob o mesmo timeout e regra de revisão.

Registre a taxa de conclusão de tarefas, a latência p50 e p95, os tokens de entrada e saída, o número de novas tentativas de ferramentas e o tempo de correção do revisor. É também aqui que o feedback misto da comunidade se torna útil. Não decida com base em uma afirmação de que a Hy3 é excepcional ou decepcionante em abstrato. Decida com base na tarefa que você realmente pagaria para automatizar.

API hospedada ou auto-hospedagem?

Use uma API hospedada primeiro quando você estiver avaliando o modelo, o tráfego ainda for incerto ou sua equipe ainda não operar a capacidade de GPU necessária. Isso encurta o caminho para os testes acima e mantém a disponibilidade do provedor separada da lógica da sua aplicação.

Hospede localmente somente quando você tiver um motivo concreto de controle, privacidade, volume ou latência e a infraestrutura para suportá-lo. O cartão de modelo oficial recomenda oito GPUs H20-3e ou outras GPUs com grande मात्रा de memória para servir o Hy3, com receitas de vLLM ou SGLang. Essa é a recomendação de produção da Tencent, não uma afirmação de que um laptop de consumidor ofereça uma implantação equivalente. Meça o custo de reservas de GPU, upgrades, monitoramento, batching e responsabilidade de plantão em relação à cobrança do serviço hospedado antes de tratar pesos abertos como infraestrutura gratuita.

Preço e disponibilidade podem mudar mais rápido do que os pesos

A Tencent listou os preços da API Hy3 em 1 RMB por milhão de tokens de entrada, 4 RMB por milhão de tokens de saída e 0,25 RMB por milhão de tokens de entrada em cache em 6 de julho. Use isso como um ponto de referência datado e, em seguida, confirme o preço real do endpoint antes de entrar em produção. O plano gratuito de um provedor, o crédito introdutório ou um alias temporário de modelo gratuito são uma disponibilidade para um experimento, não uma promessa permanente de custo por unidade.

Para uma verificação simples de custo, 100 solicitações diárias contendo 20K tokens de entrada e 1K tokens de saída usam 2M tokens de entrada e 0.1M tokens de saída. No preço de referência publicado pela Tencent, isso equivale a 2.4 RMB por dia, ou cerca de 72 RMB por 30 dias. Se todos os 2M tokens de entrada se qualificarem para preço em cache, o mesmo cálculo resulta em 0.9 RMB por dia. Esta é uma estimativa baseada apenas em tokens: ela exclui a margem do provedor, limites do plano gratuito, novas tentativas e qualquer contexto que sua aplicação adicione.

Ao orçar um teste, inclua o contexto recuperado, o prompt do sistema, as definições de ferramenta, as novas tentativas e a saída produzida pela configuração de raciocínio escolhida. Não escolha Hy3 quando a entrada principal for visual, quando uma implantação local leve for um requisito obrigatório ou quando a aplicação não puder validar os argumentos da ferramenta e os efeitos colaterais subsequentes.

Para um agente com muito texto que precisa de uma janela de contexto grande, raciocínio configurável e pesos abertos, o Hy3 é um modelo razoável para avaliar. Mantenha-o somente quando isso reduzir o tempo de correção a um custo total aceitável.

Perguntas Frequentes

O Hy3 é multimodal?

Não. Hy3 é um modelo de entrada de texto e saída de texto. Use um modelo de visão ou OCR quando a tarefa começar com imagens, digitalizações ou capturas de tela.

O que é a janela de contexto do Hy3?

O cartão de modelo da Tencent lista uma janela de contexto de 256K tokens. Um limite de contexto longo não garante que fatos relevantes serão recuperados ou seguidos, então valide isso com material de origem representativo.

Com qual modo de raciocínio do Hy3 devo começar?

Comece com no_think para trabalhos com limites definidos e sensíveis à latência. Passe para low ou high somente depois que o custo de falha da tarefa e a melhoria mensurada justificarem os tokens e o tempo extras.

Posso hospedar o Hy3 localmente?

Sim. A Tencent fornece orientações de implantação para vLLM e SGLang e recomenda oito GPUs de grande memória para o serving. O auto-hospedagem deve seguir uma decisão de capacidade e operações, e não apenas a licença de open-weight.

Uma API Hy3 gratuita é um plano de preços permanente?

Não. O acesso gratuito é específico do provedor e pode terminar ou ter seus limites alterados. Confirme os termos atuais do provedor e a tarifa paga antes de se comprometer com um fluxo de trabalho de produção.