Todos os produtos
Search
Central de documentação

Hologres:AI_EMBED

Última atualização: Jul 01, 2026

Calcula um vetor contínuo de dimensão fixa para uma entrada de texto ou imagem.

Pré-requisitos

Antes de usar esta função, implante o modelo necessário no console do Hologres. Para mais informações, consulte Managed models.

Sintaxe

Calcula um vetor contínuo de dimensão fixa para uma entrada de texto ou imagem.

-- Compute a text embedding vector
SELECT ai_embed([model], content);

-- Compute an image embedding vector (via FILE object)
SELECT ai_embed([model], file);

-- Compute an image embedding vector (via BYTEA/BLOB binary data)
SELECT ai_embed(model_name TEXT, binary BYTEA, file_format TEXT);

Parâmetros

Parâmetro

Tipo

Obrigatório

Versão

Descrição

model

TEXT

Opcional

Hologres V3.2 e posterior

Nome de um modelo de embedding implantado.

content

TEXT

Obrigatório para embedding de texto

Hologres V3.2 e posterior

Texto de entrada. Deve ser do tipo caractere (char, varchar ou text). Retorna NULL se o valor for NULL ou uma string vazia. Compatível com modelos gerenciados pelo Hologres e modelos integrados de nó de IA. Para detalhes, consulte Managed models.

file

FILE

Obrigatório para embedding de imagem

Hologres V4.0 e posterior

Objeto FILE, geralmente um objeto FILE de imagem. Retorna NULL se o valor for NULL. Compatível com modelos gerenciados pelo Hologres e modelos integrados de nó de IA. Para a lista de modelos, consulte a tabela de modelos compatíveis abaixo.

binary_data

BYTEA

Obrigatório para embedding de imagem

Hologres V4.2 e posterior

Dados binários de imagem. Compatível com o tipo BYTEA de tabelas internas do Hologres e o tipo BLOB de tabelas externas Paimon. Apenas modelos gerenciados pelo Hologres são compatíveis.

file_format

TEXT

Obrigatório para embedding de imagem

Hologres V4.2 e posterior

Formato da imagem. Necessário ao usar a entrada binary_data. Os formatos compatíveis incluem 'jpg', 'png', 'webp', 'gif', 'bmp' e 'heic'.

Valor de retorno

  • Retorna um vetor com base no modelo utilizado. A origem do modelo pode ser Managed models ou AI resources.

  • Retorna NULL se o parâmetro content for NULL ou uma string vazia.

  • Retorna NULL se o parâmetro FILE for NULL.

Modelos compatíveis

Os modelos de texto e imagem podem ser modelos gerenciados pelo Hologres ou modelos integrados de nó de IA. O tipo BYTEA aceita apenas modelos gerenciados pelo Hologres. Ao utilizar um modelo gerenciado, os formatos são os seguintes. Para mais limites de uso, consulte Managed models.

Nota
  • Os nomes dos modelos na tabela a seguir usam hifens (por exemplo, qwen3-vl-embedding). Ao chamar esses modelos em SQL, substitua os hifens por underscores (por exemplo, qwen3_vl_embedding).

  • Os modelos de vídeo estão disponíveis apenas nas regiões de Pequim e Singapura. Os modelos integrados de nó de IA exigem Hologres V3.2 ou posterior (as séries CLIP e Qwen3-Embedding também exigem V3.2 ou posterior).

Modelo

Origem

Dimensões

Texto

Imagem

Vídeo

text-embedding-v1

Modelos Gerenciados

1.536

Compatível

Não compatível

Não compatível

text-embedding-v2

1.536

Compatível

Não compatível

Não compatível

text-embedding-v3

2.048 / 1.536 / 1.024 (padrão) / 768 / 512 / 256 / 128 / 64

Compatível

Não compatível

Não compatível

text-embedding-v4

1.024 (padrão) / 768 / 512 / 256 / 128 / 64

Compatível

Não compatível

Não compatível

tongyi-embedding-vision-plus

1.152

Mais de 30 idiomas, incluindo chinês, inglês, japonês e coreano

JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI (URL ou Base64)

MP4, MPEG, MOV, MPG, WEBM, AVI, FLV, MKV (apenas URL)

tongyi-embedding-vision-flash

768

Compatível

JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI (URL ou Base64)

MP4, MPEG, MOV, MPG, WEBM, AVI, FLV, MKV (apenas URL)

multimodal-embedding-v1

1.024

Chinês e inglês

JPG, PNG, BMP (URL ou Base64)

Uma única solicitação pode conter até 20 elementos de conteúdo no total, com no máximo 1 imagem e 1 vídeo. Elementos de texto podem chegar a 20, compartilhando o limite total de contagem.

qwen3-vl-embedding

2.560 (padrão) / 2.048 / 1.536 / 1.024 / 768 / 512 / 256

33 idiomas, incluindo chinês, inglês, japonês, coreano, francês e alemão

JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI (URL ou Base64)

MP4, AVI, MOV (apenas URL)

qwen2.5-vl-embedding

2.048 / 1.024 (padrão) / 768 / 512

11 idiomas, incluindo chinês, inglês, japonês, coreano, francês e alemão

—

—

iic/nlp_gte_sentence-embedding_chinese-base

Nó de IA do Hologres

768

Compatível

Não compatível

Não compatível

iic/nlp_gte_sentence-embedding_chinese-large

1.024

Compatível

Não compatível

Não compatível

iic/nlp_gte_sentence-embedding_chinese-small

512

Compatível

Não compatível

Não compatível

Qwen/Qwen3-Embedding-0.6B

—

Compatível

Não compatível

Não compatível

Qwen/Qwen3-Embedding-4B

—

Compatível

Não compatível

Não compatível

Qwen/Qwen3-Embedding-8B

—

Compatível

Não compatível

Não compatível

BAAI/bge-base-en-v1.5

768

Compatível

Não compatível

Não compatível

BAAI/bge-base-zh-v1.5

768

Compatível

Não compatível

Não compatível

BAAI/bge-large-en-v1.5

1.024

Compatível

Não compatível

Não compatível

BAAI/bge-large-zh-v1.5

1.024

Compatível

Não compatível

Não compatível

BAAI/bge-small-en-v1.5

384

Compatível

Não compatível

Não compatível

BAAI/bge-small-zh-v1.5

512

Compatível

Não compatível

Não compatível

clip-ViT-B-16

512

Compatível

Compatível

Não compatível

clip-ViT-B-32-multilingual-v1

512

Compatível

Compatível

Não compatível

clip-ViT-B-32

512

Compatível

Compatível

Não compatível

clip-ViT-L-14

768

Compatível

Compatível

Não compatível

Exemplos

Embedding de texto

Nota

O exemplo a seguir omite o parâmetro de nome do modelo. Quando o nome do modelo é omitido, chame primeiro set_ai_function_info para definir um modelo padrão. Caso contrário, a função retornará um erro. Também é possível especificar o nome do modelo diretamente na função, por exemplo, ai_embed('text_embedding_v4', 'seu texto').

-- Text embedding
SELECT ai_embed('Hologres is a one-stop real-time data warehousing engine independently developed by Alibaba. It supports real-time ingestion, real-time updates, real-time processing, and real-time analytics over massive datasets.');

-- Result (1024-dimension vector example)
{-0.020090256,-0.009496426,-0.01584659,0.014317295,...}

Embedding de imagem (objeto FILE)

Nota

Este recurso é compatível com o Hologres V4.0 e posterior.

-- Image embedding via an OSS FILE object
SELECT ai_embed('qwen3_vl_embedding', to_file('oss://****', 'oss-cn-hangzhou-internal.aliyuncs.com', 'acs:ram::****'));

-- Result (2560-dimension vector)
{-0.000733634,-0.00160808,0.0354091,...}

Embedding de imagem (binário BYTEA)

Nota

Este recurso é compatível com o Hologres V4.2 e posterior.

Método 1: Passar dados binários diretamente

-- Convert an image to BYTEA and compute its embedding (supports webp, jpg, png, and other formats)
SELECT ai_embed('qwen3_vl_embedding',
                decode('/9j/4AAQSkZJRgABAQEAYABgAAD...', 'base64'),
                'jpg');

Método 2: Ler dados BYTEA de uma tabela interna do Hologres

-- Create an image storage table
CREATE TABLE image_table (
    image_name TEXT,
    image_bin BYTEA
);

-- Insert image data
INSERT INTO image_table VALUES
('concert.webp', decode('...webp_binary...', 'base64')),
('cat.png', decode('...png_binary...', 'base64'));

-- Generate embeddings using ai_embed
SELECT image_name,
       ai_embed('qwen3_vl_embedding', image_bin,
                CASE
                  WHEN image_name LIKE '%.webp' THEN 'webp'
                  WHEN image_name LIKE '%.png' THEN 'png'
                  WHEN image_name LIKE '%.jpg' THEN 'jpg'
                END) as embedding
FROM image_table;

Método 3: Ler dados BLOB de uma tabela externa Paimon (Hologres V4.2 e posterior)

-- Paimon external table (with a BLOB column)
CREATE EXTERNAL TABLE paimon_db.image_blob_table (
    id INT,
    image_name TEXT,
    picture BYTEA  -- Paimon BLOB is mapped to BYTEA
)
WITH (...);

-- Generate embeddings directly from Paimon BLOB data
SELECT id, image_name,
       ai_embed('qwen3_vl_embedding', picture, 'jpg') as embedding
FROM paimon_db.image_blob_table;

Casos de uso típicos

Cenário 1: Busca vetorial de imagens com tabelas internas do Hologres

Este cenário implanta o modelo qwen3-vl-embedding e demonstra o fluxo completo de embedding de imagens, busca de similaridade imagem-imagem e busca texto-imagem usando indexação vetorial.

Nota

Este recurso é compatível com o Hologres V4.2 e posterior.

Etapa 1: Preparar dados

-- 0. Create a source image table (stores raw image binary data)
CREATE TABLE source_image_table (
    image_id SERIAL PRIMARY KEY,
    image_name TEXT,
    image_bin BYTEA,
    image_format TEXT
);

-- Insert image data (example: read from local files and insert)
INSERT INTO source_image_table (image_name, image_bin, image_format) VALUES
('concert.webp', decode('UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASo...', 'base64'), 'webp'),
('cat.png', decode('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', 'base64'), 'png'),
('dog.jpg', decode('/9j/4AAQSkZJRgABAQEAYABgAAD//gA7Q1JFQVRPUjogZ2QtanBlZyB2MS4wICh1c2luZyBJSkcgSlBFRyB2ODAp', 'base64'), 'jpg');

-- 1. Create a target table with a vector index
CREATE TABLE image_search_table (
    image_id SERIAL PRIMARY KEY,
    image_name TEXT,
    image_bin BYTEA,
    image_format TEXT,
    embedding float4[] CHECK (array_ndims(embedding) = 1 AND array_length(embedding, 1) = 2560)
) WITH (
    vectors = '{ "embedding": { "algorithm": "HGraph", "distance_method": "Euclidean", "builder_params": { "base_quantization_type": "sq8_uniform", "max_degree": 64, "ef_construction": 400 } } }'
);

-- 2. Insert images from the source table and generate vectors
INSERT INTO image_search_table (image_name, image_bin, image_format, embedding)
SELECT image_name, image_bin, image_format,
       ai_embed('qwen3_vl_embedding', image_bin, image_format)
FROM source_image_table;

Etapa 2: Busca de similaridade de imagem

-- 3. Image-to-image similarity search (approximate nearest neighbor)
SELECT a.image_name as query_image,
       b.image_name as result_image,
       approx_euclidean_distance(a.embedding, b.embedding) as distance
FROM image_search_table a,
     image_search_table b
WHERE a.image_id = 1
ORDER BY distance ASC;

-- Sample result
--  query_image  | result_image | distance
-- --------------+--------------+----------
--  concert.webp | concert.webp |        0
--  concert.webp | cat.png      | 15.23457
--  concert.webp | dog.jpg      | 18.45679

Etapa 3: Busca de texto para imagem

-- 4. Text-to-image search (multimodal retrieval)
SELECT image_id, image_name,
       approx_euclidean_distance(
           embedding,
           ai_embed('qwen3_vl_embedding', 'concert photo')
       ) as text_img_distance
FROM image_search_table
ORDER BY text_img_distance ASC;

-- Sample result
--  image_id | image_name   | text_img_distance
-- ----------+--------------+-------------------
--         1 | concert.webp |          8.123456
--         3 | dog.jpg      |         22.345678
--         2 | cat.png      |         25.678901

Cenário 2: Indexação vetorial offline a partir de tabelas externas Paimon

Este cenário lê o tipo BLOB do Paimon e demonstra o fluxo completo de embedding e busca de dados BLOB do Paimon, permitindo consultas aceleradas em dados não estruturados.

Nota

Este recurso é compatível com o Hologres V4.2 e posterior.

O tipo BLOB no Paimon pode ser gravado via Flink ou Spark. Este tópico não aborda esse processo.

Etapa 1: Preparar dados

-- 0. Create an External Database to connect to the Paimon data source
CREATE EXTERNAL DATABASE paimon_blob_bj
WITH (
    catalog_type 'paimon'
    metastore_type 'dlf-rest'
    dlf_catalog 'paimon_bj'
    dlf_access_id 'xxxx'
    dlf_access_key '***'
);
-- Create an external schema
CREATE EXTERNAL SCHEMA paimon_blob_bj.test_paimon_db;

-- 1. Create a Paimon external table (with a BLOB column)
CREATE EXTERNAL TABLE paimon_blob_bj.test_paimon_db.image_table (
    id INT,
    image_name TEXT,
    picture BYTEA  -- Paimon BLOB is mapped to BYTEA
)
WITH (
   "table_format" = 'paimon',
    "file_format" = 'orc',
    "bucket" = '1',
    "bucket-key" = 'id'
);

-- 2. Create a Hologres target vector table (with a vector index)
CREATE TABLE public.image_vector_table (
    id SERIAL PRIMARY KEY,
    image_name TEXT,
    picture BYTEA,
    image_format TEXT,
    embedding float4[] CHECK (array_ndims(embedding) = 1 AND array_length(embedding, 1) = 2560)
) WITH (
    vectors = '{
        "embedding": {
            "algorithm": "HGraph",
            "distance_method": "Euclidean",
            "builder_params": {
                "base_quantization_type": "sq8_uniform",
                "max_degree": 64,
                "ef_construction": 400
            }
        }
    }'
);

Etapa 2: Carregar dados do Paimon na tabela vetorial do Hologres (opcional)

Esta etapa é opcional. Importe dados do Paimon para o Hologres para obter consultas aceleradas ou consulte a tabela Paimon diretamente, conforme seus requisitos.

-- 3. Read BLOB data from the Paimon external table, generate vectors, and write to Hologres
INSERT INTO image_vector_table (id, image_name, picture, image_format, embedding)
SELECT
    id,
    image_name,
    picture,
    'jpg',
    ai_embed('qwen3_vl_embedding', picture, 'jpg')
FROM paimon_blob_bj.test_paimon_db.image_table;

Etapa 3: Busca de similaridade de imagem

SELECT
    a.id as query_id,
    a.image_name as query_image,
    b.id as result_id,
    b.image_name as result_image,
    approx_euclidean_distance(a.embedding, b.embedding) as distance
FROM image_vector_table a,
     image_vector_table b
WHERE a.id = 1
ORDER BY distance ASC
LIMIT 5;

-- Sample result
--  query_id | query_image  | result_id | result_image | distance
-- ----------+--------------+-----------+--------------+----------
--         1 | concert.webp |         1 | concert.webp |        0
--         1 | concert.webp |         3 | dog.jpg      | 15.23457
--         1 | concert.webp |         2 | cat.png      | 18.45679

Etapa 4: Busca de texto para imagem

SELECT
    id,
    image_name,
    approx_euclidean_distance(
        embedding,
        ai_embed('qwen3_vl_embedding', 'concert photo')
    ) as text_img_distance
FROM image_vector_table
ORDER BY text_img_distance ASC
LIMIT 5;

-- Sample result
--  id | image_name   | text_img_distance
-- ----+--------------+-------------------
--   1 | concert.webp |          8.123456
--   3 | dog.jpg      |         22.345678
--   2 | cat.png      |         25.678901

Considerações

  • Seleção de modelo

    • O embedding de imagem requer um modelo multimodal como qwen3_vl_embedding (2.560 dimensões) ou tongyi_embedding_vision_plus (1.152 dimensões).

    • O embedding de texto utiliza um modelo apenas de texto, como text_embedding_v4 (1.024 dimensões).

  • Dimensões do vetor

    • Modelos diferentes retornam vetores com dimensões distintas. A restrição CHECK na definição da tabela deve corresponder à dimensão de saída do modelo.

    • qwen3_vl_embedding: 2.560 dimensões.

    • tongyi_embedding_vision_plus: 1.152 dimensões.

    • text_embedding_v4: 1.024 dimensões.

  • Otimização de desempenho

    • Crie um índice vetorial HGraph na coluna vetorial para buscas de vizinho mais próximo aproximado.

    • Para grandes conjuntos de dados, use INSERT...SELECT para construir vetores offline.

  • Tratamento de erros

    • Retorna NULL se binary_data for NULL.

    • A função retorna um erro se file_format não for compatível.

    • A função retorna um erro se a imagem estiver corrompida ou em um formato inválido.