Como gerar embeddings multimodais em Azure AI & Machine Learning

Gerar embeddings multimodais (texto + imagem) permite comparar e pesquisar conteúdos heterogéneos usando uma representação comum. Este tutorial mostra como criar, testar e usar embeddings multimodais em Azure AI & Machine Learning para tarefas como pesquisa semântica ou clustering.

Pré-requisitos

• Conta Azure com subscrição activa e permissões para criar recursos.
• Azure OpenAI Service ou endpoint de embeddings do Azure AI com suporte multimodal.
• Azure Machine Learning workspace (opcional para experimentação e deploy).
• Python 3.9+ e pip; bibliotecas: requests, numpy, scikit-learn, pillow.
• Conjunto de exemplos: alguns ficheiros de imagem (.jpg/.png) e textos curtos para cada item.

Passo 1: Por que embeddings multimodais?

Embeddings convertem texto e imagens em vectores numéricos no mesmo espaço. Isso torna possível comparar um texto com uma imagem (p.ex. "cadeira vermelha") ou agrupar itens semelhantes. Em Azure AI & Machine Learning usamos um endpoint de embeddings multimodal para gerar estes vectores e depois ferramentas standard de ML para indexação e pesquisa.

Passo 2: Preparar o ambiente e as credenciais

Guarde o endpoint e a chave do serviço Azure OpenAI ou do serviço de embeddings multimodal. Instale as bibliotecas necessárias e prepare uma pasta com imagens e um ficheiro CSV com texto associado.

python -m venv venv && source venv/bin/activate
pip install requests numpy scikit-learn pillow
export AZURE_EMBED_ENDPOINT="https://seu-endpoint.openai.azure.com"
export AZURE_EMBED_KEY="sua_chave"

Passo 3: Função mínima para gerar embedding de texto

Chame o endpoint de embeddings para texto. O exemplo usa requests e supõe um endpoint compatível com a API de embeddings do Azure OpenAI.

import os, requests, numpy as np

ENDPOINT = os.environ['AZURE_EMBED_ENDPOINT']
KEY = os.environ['AZURE_EMBED_KEY']
HEADERS = {"api-key": KEY, "Content-Type": "application/json"}

def embed_text(text):
    url = ENDPOINT + "/openai/deployments/embeddings/deploy-id/embeddings?api-version=2024-06-01"
    data = {"input": text}
    r = requests.post(url, headers=HEADERS, json=data)
    r.raise_for_status()
    vec = r.json()["data"][0]["embedding"]
    return np.array(vec, dtype=float)

Passo 4: Gerar embedding de imagem (pré-processamento)

Alguns endpoints multimodais aceitam imagem como input directo; noutros casos, convertemos a imagem para base64 ou extraímos características locais com um modelo leve. Aqui mostramos como enviar imagem em base64 caso o endpoint aceite.

import base64
from PIL import Image
import io

def embed_image(path):
    with open(path, "rb") as f:
        b64 = base64.b64encode(f.read()).decode('utf-8')
    url = ENDPOINT + "/openai/deployments/embeddings-multimodal/deploy-id/embeddings?api-version=2024-06-01"
    data = {"input": {"image": b64}}
    r = requests.post(url, headers=HEADERS, json=data)
    r.raise_for_status()
    vec = r.json()["data"][0]["embedding"]
    return np.array(vec, dtype=float)

Passo 5: Construir um índice simples e fazer pesquisa semântica

Guarde todos os vectores num array e use cosseno para medir similaridade. Abaixo um exemplo simples com scikit-learn para calcular distâncias e devolver os top-k semelhantes.

from sklearn.metrics.pairwise import cosine_similarity

# Exemplo de colecção mista
items = [
    {"id": "img1", "type": "image", "path": "images/cadeira_vermelha.jpg"},
    {"id": "txt1", "type": "text", "text": "cadeira vermelha em madeira"},
]

vectors = []
meta = []
for it in items:
    if it['type'] == 'image':
        v = embed_image(it['path'])
    else:
        v = embed_text(it['text'])
    vectors.append(v)
    meta.append(it)

vectors = np.vstack(vectors)

def search(query_text, top_k=3):
    qv = embed_text(query_text).reshape(1, -1)
    sims = cosine_similarity(qv, vectors)[0]
    idx = sims.argsort()[::-1][:top_k]
    return [(meta[i], float(sims[i])) for i in idx]

# Exemplo de pesquisa
print(search("cadeira vermelha"))

Passo 6: Erros comuns e como os resolver

Erros frequentes: 401/403 (chave ou endpoint errados), 415 (formato da imagem não suportado), vectores de dimensões diferentes (usar o mesmo deployment/modelo). Verifique o api-version e o deploy-id; se o endpoint não suportar imagem em base64, use um modelo local para extrair características antes de comparar.

Verificar o resultado

Teste com várias queries textuais e compare as imagens/textos devolvidos. O resultado está correcto se itens semanticamente relacionados aparecem no topo. Verifique também que os embeddings têm dimensão fixa e que a similaridade cosseno devolve valores próximos de 1 para itens idênticos.

Conclusão

Com embeddings multimodais em Azure AI & Machine Learning consegue unir texto e imagem no mesmo espaço vetorial para pesquisa semântica, clustering ou classificação. Próximos passos: indexar vectores com FAISS ou Azure Cognitive Search para produção, e experimentar thresholds de similaridade. Dica: comece com um pequeno conjunto e verifique as dimensões do embedding antes de escalar.