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.
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
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)
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)
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.
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.
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.