hunyuan-vision

Технические характеристики hunyuan-vision

Что такое hunyuan-vision?

hunyuan-vision — мультимодальная модель понимания изображений от Tencent Hunyuan, доступная через совместимый с OpenAI API. В официальных примерах Tencent она используется для задач формата «image-to-text», когда пользователь отправляет подсказку вместе с изображением, а модель отвечает на вопросы, например о том, что показано на изображении.

На практике это делает hunyuan-vision подходящей для приложений, которым требуется визуальное рассуждение в чат‑процессе, таких как подписи к изображениям, описание сцен, интерпретация интерфейсов или скриншотов, анализ изображений товаров и общий визуальный ответ на вопросы. Схема интеграции особенно удобна для команд, уже использующих клиенты в стиле OpenAI, поскольку Tencent заявляет, что разработчики могут переключиться, заменив только конечную точку и конфигурацию ключа API.

Основные возможности hunyuan-vision

• Мультимодальное понимание изображений: hunyuan-vision принимает в одном запросе и текст, и изображение, что позволяет вести диалоги с учётом визуального контента и отвечать на вопросы о загруженных изображениях.
• Совместимый с OpenAI интерфейс: Tencent предоставляет hunyuan-vision через ту же общую структуру запросов, что и Chat Completions, что снижает усилия при миграции существующих ИИ‑приложений.
• Гибкие способы передачи изображений: официальные примеры демонстрируют поддержку стандартных удалённых URL изображений, а также data URL, кодированных в base64, что удобно как для публичных ресурсов, так и для локально обработанных файлов.
• Интеграция, удобная для SDK: Tencent явно документирует использование с SDK OpenAI на Python, Node.js, Go, а также с HTTP‑запросами в стиле cURL, что упрощает встраивание в существующие бэкенд‑сервисы.
• Чат‑ориентированный рабочий процесс: поскольку модель предоставляется как модель chat completion, hunyuan-vision органично подходит для разговорных приложений, ассистентов и инструментальных цепочек, где запросы уже строятся вокруг messages.
• Учёт токенов изображений по использованию: Tencent отмечает, что стоимость зависит от размера изображения; потребление токенов на одно изображение указывается диапазоном, а не фиксированной величиной.

Как получить доступ и интегрировать hunyuan-vision

Шаг 1: Получите ключ API

Чтобы получить доступ к hunyuan-vision, сначала создайте и защитите ключ API через консоль провайдера. Tencent документирует доступ к совместимому с OpenAI Hunyuan API по ключу API; ключ передаётся в запросах как токен типа Bearer. Храните ключ в переменной окружения, например HUNYUAN_API_KEY, и избегайте его раскрытия в клиентском коде или публичных репозиториях.

Шаг 2: Отправляйте запросы к API hunyuan-vision

Используйте совместимый с OpenAI эндпоинт и укажите hunyuan-vision в качестве имени модели.

curl --location 'https://api.hunyuan.cloud.tencent.com/v1/chat/completions' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HUNYUAN_API_KEY" \
  --data '{
    "model": "hunyuan-vision",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What is in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/image.jpg"
            }
          }
        ]
      }
    ]
  }'

Вы также можете использовать совместимые с OpenAI SDK, указав клиенту базовый URL Hunyuan:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("HUNYUAN_API_KEY"),
    base_url="https://api.hunyuan.cloud.tencent.com/v1",
)

response = client.chat.completions.create(
    model="hunyuan-vision",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this image."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    },
                },
            ],
        }
    ],
)

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

Эта структура запроса соответствует официальным примерам Tencent, совместимым с OpenAI, для hunyuan-vision.

Шаг 3: Получайте и проверяйте результаты

Считывайте сгенерированный ответ из первого варианта, как правило response.choices[0].message.content, при использовании совместимого с OpenAI SDK. В продакшене проверьте доступность URL изображения или корректность вашего payload в base64, а затем сверяйте возвращённое описание с требованиями приложения по точности, безопасности и единообразию форматирования. Примеры Tencent демонстрируют стандартную обработку ответов chat‑completions, поэтому существующие конвейеры проверки и логирования обычно можно переиспользовать с минимальными изменениями.