Início Rápido da API Hy3 para Fluxos de Trabalho Agênticos e de Contexto Longo

O Hy3 da Tencent está disponível na Novita AI com o ID do modelo tencent/hy3, um endpoint chat/completions compatível com OpenAI, uma janela de contexto de 256K e suporte para chamada de funções, saídas estruturadas e três modos de raciocínio. Este guia de início rápido cobre a configuração para desenvolvedores: configure seu cliente, envie sua primeira requisição, use chamada de funções, ative o raciocínio e entenda os limites de taxa antes de construir.

Quando Usar Este Guia de Início Rápido

Use este guia quando precisar de uma requisição funcional para o Hy3 antes de escrever qualquer código adicional. Ele cobre um caminho prático: escolha o ID do modelo, autentique-se, envie uma requisição de teste e depois estenda para chamada de funções ou raciocínio conforme a necessidade da sua carga de trabalho.

A arquitetura do Hy3 — 295B total, 21B ativos MoE — é projetada para equilibrar qualidade e eficiência em escala. Vale a pena considerar quando você precisa de:

• Processamento de documentos de contexto longo (a janela de 256K comporta aproximadamente 200.000 palavras em uma única chamada).
• Diálogo de múltiplas turnas que se beneficia de um grande orçamento de parâmetros ativos.
• Tarefas agênticas onde chamada de ferramentas e formatação confiável de argumentos são importantes.
• Assistência de código que abrange grandes bases de código sem necessidade de fragmentação.

Este guia cobre apenas o caminho de integração via API pela Novita AI. Não cobre auto-hospedagem, fine-tuning ou portabilidade para outros backends de inferência.

Passo 1: Obtenha Sua Chave de API da Novita

Crie uma conta na Novita AI e navegue até a seção de chaves de API no seu console. Gere uma chave e armazene-a em uma variável de ambiente. Mantenha-a fora de código do lado do cliente, bundles frontend e repositórios públicos.

export NOVITA_API_KEY="sua_chave_api"

Se você já usa o SDK Python da OpenAI ou clientes compatíveis com OpenAI em outros projetos, a configuração aqui é a mesma — altere a URL base e o nome do modelo, nada mais.

Passo 2: Confirme o ID do Modelo e o Endpoint

Estes três valores são tudo que você precisa para configuração:

Item	Valor
Chave de API	Sua chave de API da Novita AI, armazenada como variável de ambiente
URL base compatível com OpenAI	https://api.novita.ai/openai
Endpoint de chat completions	POST https://api.novita.ai/openai/v1/chat/completions
ID do modelo	tencent/hy3

Use tencent/hy3 em todas as chamadas de API. Em UI ou documentação voltada ao usuário, use o nome de exibição “Hy3”.

O índice de documentação da Novita AI lista a URL base compatível com OpenAI, e a referência da API de chat completions documenta a forma completa da requisição e resposta.

Passo 3: Verifique Preços, Limites e Detalhes do Modelo

Valores atuais da página do modelo Hy3 na Novita AI:

Campo	Valor
Nome de exibição	Hy3
ID do modelo na API	tencent/hy3
Série do modelo	Hunyuan
Arquitetura	MoE, 295B total / 21B ativos
Endpoint	chat/completions
Modalidades de entrada	Texto
Modalidades de saída	Texto
Janela de contexto	262.144 tokens
Máx. tokens de saída	262.144 tokens
Recursos	Serverless, chamada de funções, saídas estruturadas, raciocínio
Preço de entrada	Listado a $0 / M tokens (verifique a taxa atual na página do modelo)
Preço de saída	Listado a $0 / M tokens (verifique a taxa atual na página do modelo)

Os limites de taxa escalam por nível de conta (T1–T5) e são medidos em requisições por minuto (RPM) e tokens por minuto (TPM). Os limites atuais e limites por nível estão listados na documentação de limites de taxa da Novita AI.

Preços e limites de taxa podem mudar. Verifique a página do modelo Hy3 e a página de preços da Novita AI antes de se comprometer com qualquer estimativa de custo.

Passo 4: Envie Sua Primeira Requisição

Comece com uma requisição de texto simples para confirmar autenticação, roteamento do modelo e análise da resposta. Mantenha o prompt curto para testar a conectividade, não a qualidade da saída.

Exemplo com 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": "Você é um assistente técnico conciso."
      },
      {
        "role": "user",
        "content": "Descreva a principal compensação entre arquiteturas MoE e transformer densas em três frases."
      }
    ],
    "max_tokens": 256,
    "temperature": 0.3
  }'

Uma resposta bem-sucedida retorna a forma padrão de chat completions: um array choices, uma mensagem com content, metadados de modelo e criação, e um objeto usage com contagens de tokens de prompt, conclusão e total.

Use este teste de fumaça para verificar:

• A chave de API é válida e o cabeçalho de autorização está formatado corretamente.
• O ID do modelo tencent/hy3 é aceito sem erro 404 ou modelo não encontrado.
• Seu cliente pode analisar choices[0].message.content.
• O uso de tokens é registrado para que você possa monitorar custos desde a primeira requisição.

Exemplo em Python

O SDK Python da OpenAI funciona com a Novita AI quando você define a 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": "Você é um assistente técnico conciso."},
        {
            "role": "user",
            "content": "Descreva a principal compensação entre arquiteturas MoE e transformer densas em três frases.",
        },
    ],
    max_tokens=256,
    temperature=0.3,
)

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

Passo 5: Leia a Resposta

A resposta segue o formato padrão de chat completions da OpenAI:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1751000000,
  "model": "tencent/hy3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Modelos MoE ativam apenas uma fração de seus parâmetros totais..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 80,
    "total_tokens": 132
  }
}

O campo finish_reason indica por que a geração parou. stop significa que o modelo atingiu um final natural. length significa que max_tokens foi atingido. Se você vir length em prompts curtos, aumente max_tokens ou reduza o prompt.

Parâmetros Principais

Parâmetro	Tipo	Efeito
model	string	Deve ser tencent/hy3
messages	array	Histórico da conversa. As funções system, user e assistant são suportadas.
max_tokens	integer	Limite de tokens de saída. Defina explicitamente; o padrão pode variar conforme o cliente.
temperature	float (0–2)	Valores menores produzem saída mais determinística. Use 0.1–0.3 para código e tarefas factuais; 0.7–1.0 para saídas criativas ou variadas.
top_p	float (0–1)	Alternativa à temperatura para amostragem. Evite definir ambos ao mesmo tempo.
stream	boolean	Defina como true para receber tokens como um stream. Requer manipulação de eventos server-sent no seu cliente.
tools	array	Definições de ferramentas para chamada de funções. Veja a seção de chamada de funções abaixo.
tool_choice	string ou object	Controla qual ferramenta o modelo chama. "auto" permite que o modelo decida.

Para cargas de trabalho de contexto longo, o Hy3 suporta até 262.144 tokens de entrada. Gerencie o uso de tokens por chamada e monitore o custo cumulativo se estiver processando documentos grandes ou longos históricos de conversa.

Chamada de Funções

O Hy3 suporta chamada de funções através do parâmetro tools. Use-o quando quiser que o modelo retorne argumentos estruturados em vez de texto — roteando uma requisição para uma ação específica, analisando entrada do usuário em campos tipados ou conduzindo um fluxo de trabalho em várias etapas.

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": "search_knowledge_base",
            "description": "Pesquisar uma base de conhecimento de produtos para respostas a consultas de clientes.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "A pergunta ou tópico do cliente a ser pesquisado.",
                    },
                    "max_results": {
                        "type": "integer",
                        "description": "Número máximo de resultados a retornar. Padrão é 5.",
                    },
                },
                "required": ["query"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "Você é um assistente de suporte ao cliente. Use a ferramenta de pesquisa para encontrar respostas relevantes."},
        {
            "role": "user",
            "content": "Qual é a política de devolução para eletrônicos comprados nos últimos 30 dias?",
        },
    ],
    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"Ferramenta: {call.function.name}")
        args = json.loads(call.function.arguments)
        print(f"Argumentos: {args}")
else:
    print(message.content)

Quando o modelo retorna uma chamada de ferramenta, sua aplicação executa a função e depois envia o resultado de volta na conversa:

# Após executar sua função de pesquisa, envie o resultado de volta
tool_result = "Devoluções aceitas em até 30 dias com recibo original. Eletrônicos devem estar lacrados."

follow_up = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "Você é um assistente de suporte ao cliente."},
        {"role": "user", "content": "Qual é a política de devolução para eletrônicos comprados nos últimos 30 dias?"},
        message,  # mensagem de chamada de ferramenta do assistente
        {
            "role": "tool",
            "tool_call_id": message.tool_calls[0].id,
            "content": tool_result,
        },
    ],
    temperature=0.1,
)

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

Teste seus esquemas de ferramenta em consultas representativas antes de rotear tráfego de produção. A qualidade da extração de argumentos de função depende de quão claramente você descreve cada parâmetro e seus valores esperados.

Modo de Raciocínio

O Hy3 lista o raciocínio como um recurso suportado na página do modelo da Novita AI. Modelos com capacidade de raciocínio pensam em um problema antes de produzir uma resposta final, o que pode melhorar a qualidade da saída em problemas complexos de múltiplas etapas — depuração de código, matemática de múltiplas etapas, análise de documentos longos e tarefas de planejamento.

A API de chat completions da Novita AI suporta parâmetros relacionados ao raciocínio (separate_reasoning, enable_thinking) para modelos selecionados. Se esses parâmetros são aceitos pelo tencent/hy3 e o formato exato da requisição não estão confirmados na documentação atual da Novita. Antes de incorporar comportamento de raciocínio em um fluxo de produção com o Hy3, execute uma chamada de teste e verifique se a resposta inclui um campo reasoning_content em choices[0].message.

Para nomes de parâmetros verificados e IDs de modelo suportados, veja a referência da API de chat completions da Novita AI e o guia de Modelos de Raciocínio.

Uso de Contexto Longo

A janela de contexto de 256K do Hy3 é uma vantagem prática para tarefas que exigem manter um grande corpo de texto em uma única chamada. Casos de uso onde isso importa:

• Análise de documentos: Envie um contrato completo, artigo de pesquisa ou especificação como contexto e faça perguntas direcionadas sem fragmentação.
• Revisão de base de código: Passe um arquivo grande ou vários arquivos relacionados e peça observações de arquitetura, padrões de bugs ou sugestões de refatoração.
• Histórico longo de conversa: Fluxos de trabalho agênticos que acumulam muitas turnas podem permanecer no contexto por mais tempo antes de exigir sumarização ou truncamento.

Para chamadas de contexto longo, defina max_tokens explicitamente com base no comprimento esperado da saída. Enviar 200K tokens de entrada e deixar o orçamento de tokens de saída no padrão desperdiça orçamento de contexto e pode produzir respostas 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("large_document.txt") as f:
    document_text = f.read()

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {
            "role": "system",
            "content": "Você é um assistente de análise de documentos. Forneça respostas específicas e referenciadas.",
        },
        {
            "role": "user",
            "content": f"Aqui está o documento:\n\n{document_text}\n\nResuma as principais obrigações e prazos neste documento.",
        },
    ],
    max_tokens=1024,
    temperature=0.2,
)

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

Monitore usage.prompt_tokens na resposta para rastrear quantos tokens suas entradas consomem. Para cargas de trabalho que enviam repetidamente o mesmo prompt de sistema ou preâmbulo de documento, o planejamento de limite de taxa e custo depende da contagem real de tokens do prompt, não apenas da contagem de caracteres do documento.

Solução de Problemas

401 Não Autorizado: A chave de API está faltando, expirada ou formatada incorretamente. Verifique se o cabeçalho Authorization está como Bearer <sua_chave> com um espaço e sem caracteres extras.

404 ou modelo não encontrado: O ID do modelo está errado. Confirme se a string exata tencent/hy3 corresponde ao ID mostrado na página do modelo da Novita AI. IDs de modelo diferenciam maiúsculas de minúsculas.

429 Limite de Taxa: Você excedeu as requisições ou tokens por minuto para seu nível. Adicione lógica de retry com backoff exponencial ou solicite um nível superior se sua carga de trabalho exigir consistentemente.

finish_reason: length: A resposta foi cortada porque atingiu max_tokens. Aumente o valor de max_tokens se precisar de saídas mais longas, mas lembre-se de que tokens de saída afetam custo e latência.

Resposta inicial lenta: Implantações de modelos grandes podem ter uma breve latência de inicialização a frio na primeira requisição. Requisições subsequentes ao mesmo endpoint são tipicamente mais rápidas. Se a latência for um requisito rígido, teste a taxa de transferência no seu nível de concorrência alvo antes do lançamento em produção.

Chamada de ferramenta retorna argumentos inesperados: Revise seu esquema de ferramenta. Adicione descrições mais específicas para cada parâmetro, inclua valores de exemplo no campo de descrição e liste campos obrigatórios explicitamente. Teste primeiro com esquemas simplificados e depois adicione complexidade.

FAQ

O Hy3 está disponível na Novita AI?

Sim. A Novita AI lista o Hy3 como um LLM Serverless com o ID do modelo na API tencent/hy3.

Qual é o ID correto do modelo?

Use tencent/hy3 em todas as chamadas de API. Use “Hy3” em textos voltados ao usuário.

Qual endpoint devo usar?

Use o endpoint de chat completions compatível com OpenAI: POST https://api.novita.ai/openai/v1/chat/completions. Defina a URL base como https://api.novita.ai/openai ao usar o SDK da OpenAI.

Qual é o tamanho da janela de contexto?

O Hy3 suporta uma janela de contexto de 262.144 tokens e até 262.144 tokens de saída, conforme listado na página do modelo da Novita AI.

O Hy3 suporta chamada de funções?

Sim. O Hy3 suporta chamada de funções através do parâmetro tools na requisição de chat completions. A Novita lista chamada de funções e saídas estruturadas como recursos suportados.

O Hy3 suporta raciocínio?

O raciocínio é listado como um recurso na página do modelo da Novita AI. Os parâmetros específicos de requisição para ativar o raciocínio com tencent/hy3 não estão confirmados na documentação atual da Novita. Verifique a referência da API de chat completions da Novita AI e execute uma chamada de teste para verificar o formato do parâmetro antes de incorporar comportamento de raciocínio em produção.

Quais entradas o Hy3 aceita?

O Hy3 aceita apenas entradas de texto. Ele não lista modalidades de imagem ou vídeo na página do modelo da Novita AI.

Qual é a arquitetura do Hy3?

O Hy3 usa uma arquitetura MoE (Mixture of Experts) com 295B parâmetros totais e 21B parâmetros ativos por passagem direta. Isso permite atender requisições de contexto grande a um custo computacional menor em comparação com modelos densos de qualidade similar.

Como obtenho um limite de taxa maior?

Os limites de taxa escalam por nível de conta. Os limites atuais por nível estão listados na documentação de limites de taxa da Novita AI. Entre em contato com o suporte da Novita AI para opções de upgrade.

Artigos Recomendados

• Chamada de Funções e Saídas Estruturadas na Novita AI
• Como Desenvolver um Fluxo de Trabalho Agêntico de Pesquisa Profunda com LangChain e a API LLM da Novita AI
• API do Hunyuan Image 3 na Novita AI: Guia de Geração Texto-para-Imagem