Hy3 API Quick Start для агентных и длинно-контекстных рабочих процессов

Hy3 от Tencent доступен на Novita AI с идентификатором модели tencent/hy3, OpenAI-совместимой конечной точкой chat/completions, окном контекста в 256K токенов и поддержкой вызова функций, структурированных выходных данных и трёх режимов рассуждения. Это краткое руководство охватывает настройку разработчика: настройка клиента, отправка первого запроса, использование вызова функций, включение рассуждения и понимание ограничений скорости перед началом разработки.

Когда использовать это руководство

Используйте это руководство, когда вам нужен рабочий запрос к Hy3 до написания дополнительного кода. Оно описывает практический путь: выберите идентификатор модели, авторизуйтесь, отправьте один тестовый запрос, затем расширьте до вызова функций или рассуждения по мере необходимости рабочей нагрузки.

Архитектура Hy3 — 295B всего, 21B активных MoE — спроектирована для баланса качества и эффективности в масштабе. Её стоит рассмотреть, когда вам нужны:

• Обработка длинных контекстов документов (окно в 256K токенов вмещает примерно 200 000 слов за один вызов).
• Многоходовые диалоговые сценарии, выигрывающие от большого бюджета активных параметров.
• Агентные задачи, где важен вызов инструментов и надёжное форматирование аргументов.
• Помощь в написании кода, охватывающая большие кодовые базы без дробления.

Это руководство охватывает только интеграцию через API на Novita AI. Оно не рассматривает самостоятельное развёртывание, тонкую настройку или перенос на другие инференс-бэкенды.

Шаг 1: Получение API-ключа Novita

Создайте аккаунт Novita AI и перейдите в раздел API-ключей в консоли. Сгенерируйте ключ и сохраните его в переменную окружения. Держите его подальше от клиентского кода, фронтенд-сборок и публичных репозиториев.

export NOVITA_API_KEY="your_api_key"

Если вы уже используете OpenAI Python SDK или OpenAI-совместимые клиенты в других проектах, настройка здесь та же — измените базовый URL и имя модели, больше ничего.

Шаг 2: Подтверждение идентификатора модели и конечной точки

Эти три значения — всё, что нужно для настройки:

Параметр	Значение
API-ключ	Ваш API-ключ Novita AI, хранящийся как переменная окружения
Базовый URL (OpenAI-совместимый)	https://api.novita.ai/openai
Конечная точка чат-завершений	POST https://api.novita.ai/openai/v1/chat/completions
Идентификатор модели	tencent/hy3

Используйте tencent/hy3 во всех вызовах API. В пользовательском интерфейсе или документации используйте отображаемое имя «Hy3».

Индекс документации Novita AI содержит OpenAI-совместимый базовый URL, а справочник API чат-завершений описывает полную структуру запроса и ответа.

Шаг 3: Проверка цен, лимитов и деталей модели

Текущие значения со страницы модели Hy3 на Novita AI:

Поле	Значение
Отображаемое имя	Hy3
API ID модели	tencent/hy3
Серия моделей	Hunyuan
Архитектура	MoE, 295B всего / 21B активных
Конечная точка	chat/completions
Входные модальности	Текст
Выходные модальности	Текст
Окно контекста	262,144 токена
Макс. выходных токенов	262,144 токена
Возможности	Serverless, вызов функций, структурированные выходные данные, рассуждение
Цена за ввод	Указана $0 / M токенов (проверьте текущую ставку на странице модели)
Цена за вывод	Указана $0 / M токенов (проверьте текущую ставку на странице модели)

Лимиты скорости масштабируются в зависимости от уровня аккаунта (T1–T5) и измеряются в запросах в минуту (RPM) и токенах в минуту (TPM). Текущие пороги и лимиты уровней перечислены в документации по лимитам скорости Novita AI.

Цены и лимиты скорости могут меняться. Проверьте страницу модели Hy3 и страницу цен Novita AI перед принятием решения о каких-либо оценках стоимости.

Шаг 4: Отправка первого запроса

Начните с простого текстового запроса, чтобы убедиться в работоспособности аутентификации, маршрутизации модели и парсинга ответов. Используйте короткий запрос, чтобы проверять соединение, а не качество вывода.

Пример 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": "You are a concise technical assistant."
      },
      {
        "role": "user",
        "content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences."
      }
    ],
    "max_tokens": 256,
    "temperature": 0.3
  }'

Успешный ответ возвращает стандартную структуру чат-завершений: массив choices, сообщение с content, метаданные модели и created, а также объект usage с количеством токенов запроса, завершения и общим количеством.

Используйте этот быстрый тест, чтобы проверить:

• API-ключ действителен, и заголовок авторизации отформатирован правильно.
• Идентификатор модели tencent/hy3 принимается без ошибки 404 или model-not-found.
• Ваш клиент может парсить choices[0].message.content.
• Использование токенов логируется, чтобы вы могли отслеживать затраты с первого запроса.

Пример Python

OpenAI Python SDK работает с Novita AI, если установить базовый URL:

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": "You are a concise technical assistant."},
        {
            "role": "user",
            "content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences.",
        },
    ],
    max_tokens=256,
    temperature=0.3,
)

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

Шаг 5: Чтение ответа

Ответ следует стандартному формату чат-завершений OpenAI:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1751000000,
  "model": "tencent/hy3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "MoE models activate only a fraction of their total parameters..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 80,
    "total_tokens": 132
  }
}

Поле finish_reason сообщает, почему генерация остановилась. stop означает, что модель достигла естественного окончания. length означает, что был достигнут max_tokens. Если вы видите length на коротких запросах, увеличьте max_tokens или уменьшите запрос.

Ключевые параметры

Параметр	Тип	Назначение
model	string	Должен быть tencent/hy3
messages	array	История диалога. Поддерживаются роли system, user и assistant.
max_tokens	integer	Ограничение на количество выходных токенов. Задавайте явно; значение по умолчанию может различаться в зависимости от клиента.
temperature	float (0–2)	Меньшие значения дают более детерминированный вывод. Используйте 0.1–0.3 для кода и фактологических задач; 0.7–1.0 для творческих или разнообразных выводов.
top_p	float (0–1)	Альтернатива temperature для семплинга. Избегайте установки обоих одновременно.
stream	boolean	Установите true, чтобы получать токены потоком. Требует обработки серверных событий (SSE) на вашем клиенте.
tools	array	Определения инструментов для вызова функций. См. раздел о вызове функций ниже.
tool_choice	string или object	Управляет тем, какой инструмент вызывает модель. "auto" позволяет модели решать.

Для рабочих нагрузок с длинным контекстом Hy3 поддерживает до 262,144 входных токенов. Планируйте использование токенов на один вызов и отслеживайте совокупную стоимость, если обрабатываете большие документы или длинные истории диалогов.

Вызов функций

Hy3 поддерживает вызов функций через параметр tools. Используйте его, когда хотите, чтобы модель возвращала структурированные аргументы вместо прозы — маршрутизация запроса к конкретному действию, разбор пользовательского ввода в типизированные поля или управление многошаговым рабочим процессом.

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": "Search a product knowledge base for answers to customer queries.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The customer's question or topic to search for.",
                    },
                    "max_results": {
                        "type": "integer",
                        "description": "Maximum number of results to return. Default is 5.",
                    },
                },
                "required": ["query"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a customer support assistant. Use the search tool to find relevant answers."},
        {
            "role": "user",
            "content": "What is your return policy for electronics purchased in the last 30 days?",
        },
    ],
    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"Tool: {call.function.name}")
        args = json.loads(call.function.arguments)
        print(f"Arguments: {args}")
else:
    print(message.content)

Когда модель возвращает вызов инструмента, ваше приложение выполняет функцию, а затем отправляет результат обратно в диалог:

# After executing your search function, send the result back
tool_result = "Returns accepted within 30 days with original receipt. Electronics must be unopened."

follow_up = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a customer support assistant."},
        {"role": "user", "content": "What is your return policy for electronics purchased in the last 30 days?"},
        message,  # the assistant's tool call message
        {
            "role": "tool",
            "tool_call_id": message.tool_calls[0].id,
            "content": tool_result,
        },
    ],
    temperature=0.1,
)

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

Проверяйте схемы инструментов на репрезентативных запросах перед направлением рабочего трафика. Качество извлечения аргументов функции зависит от того, насколько чётко вы описываете каждый параметр и его ожидаемые значения.

Режим рассуждения

Hy3 указывает рассуждение как поддерживаемую функцию на странице модели Novita AI. Модели, способные к рассуждению, обдумывают проблему перед выдачей окончательного ответа, что может улучшить качество вывода для сложных многошаговых задач — отладка кода, многошаговая математика, анализ длинных документов и задачи планирования.

API чат-завершений Novita AI поддерживает параметры, связанные с рассуждением (separate_reasoning, enable_thinking), для отдельных моделей. Подтверждение того, принимаются ли эти параметры для tencent/hy3 и точный формат запроса, отсутствует в текущей документации Novita. Прежде чем встраивать поведение рассуждения в рабочий процесс с Hy3, выполните тестовый вызов и проверьте, включает ли ответ поле reasoning_content в choices[0].message.

За проверенными именами параметров и поддерживаемыми идентификаторами моделей обратитесь к справочнику API чат-завершений Novita AI и руководству по моделям рассуждения.

Использование длинного контекста

Окно контекста Hy3 в 256K токенов — практическое преимущество для задач, требующих удержания большого объёма текста в одном вызове. Сценарии использования, где это важно:

• Анализ документов: Отправьте полный контракт, исследовательскую работу или спецификацию как контекст и задавайте целевые вопросы без дробления.
• Проверка кодовой базы: Передайте большой файл или несколько связанных файлов и запросите наблюдения по архитектуре, паттерны ошибок или предложения по рефакторингу.
• Длинная история диалогов: Агентные рабочие процессы с накоплением многих оборотов могут дольше оставаться в контексте, прежде чем потребуется обобщение или усечение.

Для вызовов с длинным контекстом явно задавайте max_tokens в зависимости от ожидаемой длины вывода. Отправка 200K токенов на вход и оставление бюджета выходных токенов по умолчанию тратит бюджет контекста и может привести к усечённым ответам.

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": "You are a document analysis assistant. Provide specific, referenced answers.",
        },
        {
            "role": "user",
            "content": f"Here is the document:\n\n{document_text}\n\nSummarize the key obligations and deadlines in this document.",
        },
    ],
    max_tokens=1024,
    temperature=0.2,
)

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

Отслеживайте usage.prompt_tokens в ответе, чтобы знать, сколько токенов потребляют ваши входные данные. Для рабочих нагрузок, которые многократно отправляют одно и то же системное сообщение или преамбулу документа, планирование лимитов скорости и стоимости зависит от фактического количества токенов запроса, а не только от количества символов документа.

Устранение неполадок

401 Unauthorized: API-ключ отсутствует, истёк или неправильно отформатирован. Проверьте, что заголовок Authorization имеет вид Bearer <your_key> с пробелом и без лишних символов.

404 or model not found: Идентификатор модели неверен. Убедитесь, что точная строка tencent/hy3 соответствует ID, указанному на странице модели Novita AI. Идентификаторы моделей чувствительны к регистру.

429 Rate Limit: Вы превысили количество запросов или токенов в минуту для вашего уровня. Добавьте логику повторных попыток с экспоненциальной задержкой или запросите более высокий уровень, если ваша рабочая нагрузка требует этого постоянно.

finish_reason: length: Ответ был обрезан из-за достижения max_tokens. Увеличьте значение max_tokens, если вам нужны более длинные выводы, но помните, что выходные токены влияют на стоимость и задержку.

Медленный первый ответ: Крупные развёртывания моделей могут иметь небольшую задержку холодного старта при первом запросе. Последующие запросы к той же конечной точке обычно быстрее. Если задержка является строгим требованием, протестируйте пропускную способность при целевом уровне параллелизма перед запуском в производство.

Вызов инструмента возвращает неожиданные аргументы: Пересмотрите схему инструмента. Добавьте более конкретные описания каждого параметра, включите примеры значений в поле description и явно перечислите обязательные поля. Начните с упрощённых схем, затем добавляйте сложность.

Часто задаваемые вопросы

Доступен ли Hy3 на Novita AI?

Да. Novita AI указывает Hy3 как Serverless LLM с API-идентификатором модели tencent/hy3.

Какой правильный идентификатор модели?

Используйте tencent/hy3 во всех вызовах API. Используйте «Hy3» в тексте, обращённом к пользователю.

Какую конечную точку использовать?

Используйте OpenAI-совместимую конечную точку чат-завершений: POST https://api.novita.ai/openai/v1/chat/completions. Установите базовый URL https://api.novita.ai/openai при использовании OpenAI SDK.

Насколько велико окно контекста?

Hy3 поддерживает окно контекста в 262,144 токена и до 262,144 выходных токенов, как указано на странице модели Novita AI.

Поддерживает ли Hy3 вызов функций?

Да. Hy3 поддерживает вызов функций через параметр tools в запросе чат-завершений. Novita указывает вызов функций и структурированные выходные данные как поддерживаемые функции.

Поддерживает ли Hy3 рассуждение?

Рассуждение указано как функция на странице модели Novita AI. Конкретные параметры запроса для включения рассуждения с tencent/hy3 не подтверждены в текущей документации Novita. Проверьте справочник API чат-завершений Novita AI и выполните тестовый вызов, чтобы убедиться в формате параметра перед встраиванием поведения рассуждения в производство.

Какие входные данные принимает Hy3?

Hy3 принимает только текстовые входные данные. Он не указывает модальности изображения или видео на странице модели Novita AI.

Какова архитектура Hy3?

Hy3 использует архитектуру MoE (смесь экспертов) с 295B общих параметров и 21B активных параметров на прямой проход. Это позволяет ему обслуживать запросы с большим контекстом при меньших вычислительных затратах по сравнению с плотными моделями аналогичного качества.

Как получить более высокий лимит скорости?

Лимиты скорости масштабируются в зависимости от уровня аккаунта. Текущие пороги и лимиты уровней перечислены в документации по лимитам скорости Novita AI. Свяжитесь с поддержкой Novita AI для получения информации о вариантах повышения уровня.

Рекомендуемые статьи

• Вызов функций и структурированные выходные данные на Novita AI
• Как разработать агентный рабочий процесс глубокого поиска с LangChain и LLM API Novita AI
• Hunyuan Image 3 API на Novita AI: Руководство по генерации из текста в изображение