hunyuan-vision API

Thông số kỹ thuật của hunyuan-vision

hunyuan-vision là gì?

hunyuan-vision là mô hình hiểu hình ảnh đa phương thức của Tencent Hunyuan, được cung cấp qua API tương thích OpenAI. Trong các ví dụ chính thức của Tencent, mô hình được dùng cho các tác vụ kiểu “image-to-text”, nơi người dùng gửi lời nhắc kèm một hình ảnh và mô hình trả lời các câu hỏi như nội dung hiển thị trong hình.

Về mặt thực tiễn, điều này khiến hunyuan-vision phù hợp cho các ứng dụng cần suy luận thị giác trong luồng hội thoại, như chú thích ảnh, mô tả cảnh, diễn giải giao diện hoặc ảnh chụp màn hình, phân tích ảnh sản phẩm và hỏi đáp trực quan nói chung. Cách tích hợp này đặc biệt tiện lợi cho các nhóm đã dùng client kiểu OpenAI, vì Tencent cho biết nhà phát triển chỉ cần thay endpoint và cấu hình khóa API để chuyển đổi.

Các tính năng chính của hunyuan-vision

• Hiểu hình ảnh đa phương thức: hunyuan-vision chấp nhận cả văn bản và hình ảnh trong cùng một yêu cầu, cho phép hội thoại nhận biết hình ảnh và hỏi đáp về nội dung hình được tải lên.
• Giao diện tương thích OpenAI: Tencent cung cấp hunyuan-vision theo cấu trúc yêu cầu Chat Completions tương tự, giúp giảm công sức di chuyển cho các ứng dụng AI hiện có.
• Phương thức nhập hình ảnh linh hoạt: Ví dụ chính thức cho thấy hỗ trợ cả URL ảnh từ xa chuẩn cũng như data URL base64, hữu ích khi làm việc với tài nguyên công khai hoặc tệp được xử lý cục bộ.
• Tích hợp thân thiện với SDK: Tencent nêu rõ cách dùng với OpenAI SDKs trong Python, Node.js, Go và các yêu cầu HTTP kiểu cURL, giúp dễ nhúng vào các dịch vụ backend hiện có.
• Luồng công việc dựa trên chat: Vì được cung cấp dưới dạng mô hình chat completion, hunyuan-vision phù hợp tự nhiên với các ứng dụng hội thoại, trợ lý và chuỗi công cụ đã tổ chức yêu cầu quanh messages.
• Tính toán token ảnh theo mức sử dụng: Tencent cho biết chi phí ảnh phụ thuộc kích thước ảnh, với mức tiêu thụ token mỗi ảnh được nêu theo khoảng thay vì mức cố định.

Cách truy cập và tích hợp hunyuan-vision

Bước 1: Đăng ký khóa API

Để truy cập hunyuan-vision, trước tiên hãy tạo và bảo mật khóa API qua bảng điều khiển của nhà cung cấp. Tencent cung cấp truy cập dựa trên khóa API cho Hunyuan API tương thích OpenAI, và khóa được truyền dưới dạng Bearer token trong yêu cầu. Lưu khóa trong biến môi trường như HUNYUAN_API_KEY, và tránh để lộ trong mã phía khách hay kho công khai.

Bước 2: Gửi yêu cầu tới API hunyuan-vision

Sử dụng endpoint tương thích OpenAI và chỉ định hunyuan-vision làm tên mô hình.

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"
            }
          }
        ]
      }
    ]
  }'

Bạn cũng có thể dùng các SDK tương thích OpenAI bằng cách trỏ client tới base URL của 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)

Cấu trúc yêu cầu này tuân theo các ví dụ chính thức tương thích OpenAI của Tencent dành cho hunyuan-vision.

Bước 3: Truy xuất và xác minh kết quả

Đọc câu trả lời được tạo từ lựa chọn completion đầu tiên, thường là response.choices[0].message.content khi dùng SDK tương thích OpenAI. Trong môi trường sản xuất, hãy xác minh URL ảnh có thể truy cập hoặc payload base64 hợp lệ, sau đó kiểm tra mô tả trả về theo yêu cầu của ứng dụng về độ chính xác, an toàn và tính nhất quán định dạng. Ví dụ của Tencent cho thấy cách xử lý phản hồi chat-completions chuẩn, nên các đường ống xác thực và ghi log hiện có thường có thể tái sử dụng với điều chỉnh tối thiểu.