Gere embeddings de documentos em uma tabela vetorial com AI Inference

Transforme os documentos de um bucket em trechos com vetores de um modelo de embedding do AI Inference, armazenados em uma tabela vetorial do SQL Database.

Última atualização

Ver como Markdown Configurar agente

Você transforma um documento armazenado no Object Storage em trechos, gera o embedding de cada trecho com um modelo do AI Inference e armazena os trechos e os seus vetores em uma tabela do SQL Database, a partir de uma function e da API da Azion. Para consultar a tabela por significado depois que ela guardar vetores, consulte Vector search.

Uma etapa de recuperação encontra trechos comparando vetores, então cada trecho precisa de um, produzido pelo mesmo modelo e na mesma largura do vetor de cada pergunta posterior. A function lê um documento por requisição, gera os embeddings de todos os trechos dele em uma chamada ao modelo e os grava em uma chamada à API da Azion.

  1. Uma requisição indica a key de objeto de um documento, e a function lê esse documento do bucket.
  2. A function divide o texto em trechos.
  3. Uma chamada ao modelo de embedding retorna um vetor para cada trecho.
  4. A function monta um DELETE para as linhas anteriores do documento e um INSERT por trecho e os envia ao endpoint de consulta da API da Azion.
  5. As linhas chegam à tabela vetorial, e o índice vetorial passa a cobri-las.

Pré-requisitos

Os exemplos leem o bucket my-bucket, geram embeddings com Qwen/Qwen3-Embedding-4B em 1.024 dimensões, gravam em uma tabela chamada passages e respondem em www.example.com. Substitua esses valores, <database-id>, <personal-token> e <object-key> pelos seus.

Crie a tabela vetorial

A coluna vetorial declara a largura dos vetores que guarda, e a requisição de embedding pede a mesma largura. Qwen/Qwen3-Embedding-4B retorna uma de cinco larguras, 256, 512, 1024, 2048 ou 4096, pelo campo dimensions, então uma coluna F32_BLOB(1024) corresponde a uma requisição de 1024. Um índice vetorial precisa de uma tabela com ROWID ou com uma chave primária de coluna única, e o segundo argumento dele define a métrica de distância.

Para criar a tabela e o seu índice, envie as duas instruções ao endpoint de consulta:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/sql/databases/<database-id>/query \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token <personal-token>' \
05 --header 'Content-Type: application/json' \
06 --data {"statements":[
07 "CREATE TABLE passages (id INTEGER PRIMARY KEY AUTOINCREMENT, source TEXT NOT NULL, content TEXT NOT NULL, embedding F32_BLOB(1024));",
08 "CREATE INDEX passages_idx ON passages (libsql_vector_idx(embedding, '\''metric=cosine'\''));"
09 ]}

A API responde 200 com "state": "executed" e uma entrada por instrução. Uma instrução que falha ainda responde 200, com error no lugar de results na sua entrada, então leia as duas entradas:

{"state":"executed","data":[{"results":{"columns":[],"rows":[],...}},{"results":{"columns":[],"rows":[],...}}]}

O banco de dados guarda uma tabela passages vazia e o índice passages_idx. O índice adiciona uma tabela sombra, passages_idx_shadow, que uma listagem de tabelas mostra ao lado de passages.

Gere os embeddings de um documento na tabela

A function lê o documento com a classe Storage do módulo azion:storage, que recebe o nome do bucket e nenhum token. Ela envia todos os trechos em um único array input, e o modelo responde com uma entrada por item em data, em que data[].index é a posição do trecho e data[].embedding é o seu vetor. Cada vetor entra na sua instrução como texto dentro de vector('[...]').

A rota grava no banco de dados, então ela recusa uma requisição que não traz um segredo. Para armazenar esse segredo com a Azion CLI:

azion create variables --key INGEST_SECRET --value <ingest-secret> --secret true

O comando imprime o UUID da variável que criou:

Created variable with UUID 00000000-0000-0000-0000-000000000005

Para gerar os embeddings de um documento por requisição, use este código como entrypoint da function:

JavaScript
01import Storage from 'azion:storage';
02
03const BUCKET = 'my-bucket';
04const EMBEDDING_MODEL = 'Qwen/Qwen3-Embedding-4B';
05const DIMENSIONS = 1024;
06const MAX_PASSAGE = 1500;
07const MAX_PASSAGES = 99;
08
09// Um trecho é uma sequência de parágrafos de até MAX_PASSAGE caracteres.
10function split(text) {
11 const passages = [];
12 let current = '';
13 for (const paragraph of text.split(/\n\s*\n/)) {
14 const p = paragraph.trim();
15 if (!p) continue;
16 if (current && current.length + p.length > MAX_PASSAGE) {
17 passages.push(current);
18 current = '';
19 }
20 current = current ? `${current}\n\n${p}` : p;
21 }
22 if (current) passages.push(current);
23 return passages;
24}
25
26function sqlText(value) {
27 return `'${String(value).replaceAll("'", "''")}'`;
28}
29
30async function writeRows(statements) {
31 const response = await fetch(
32 `https://api.azion.com/v4/workspace/sql/databases/${Azion.env.get('SQL_DATABASE_ID')}/query`,
33 {
34 method: 'POST',
35 headers: {
36 Accept: 'application/json',
37 Authorization: `Token ${Azion.env.get('SQL_TOKEN')}`,
38 'Content-Type': 'application/json',
39 },
40 body: JSON.stringify({ statements }),
41 },
42 );
43 if (!response.ok) {
44 throw new Error(`Azion API answered ${response.status}`);
45 }
46 const failed = (await response.json()).data.find((entry) => entry.error);
47 if (failed) {
48 throw new Error(failed.error);
49 }
50}
51
52export default {
53 async fetch(request, env, ctx) {
54 if (request.method !== 'POST') {
55 return new Response('Method not allowed', { status: 405 });
56 }
57 if (request.headers.get('Authorization') !== `Bearer ${Azion.env.get('INGEST_SECRET')}`) {
58 return new Response('Unauthorized', { status: 401 });
59 }
60 const key = new URL(request.url).searchParams.get('key');
61 if (!key) {
62 return Response.json({ error: 'key is required' }, { status: 400 });
63 }
64
65 let text;
66 try {
67 const object = await new Storage(BUCKET).get(key);
68 text = new TextDecoder().decode(await object.arrayBuffer());
69 } catch (error) {
70 return Response.json({ error: String(error) }, { status: 404 });
71 }
72 const passages = split(text);
73 if (passages.length === 0 || passages.length > MAX_PASSAGES) {
74 return Response.json({ error: `${passages.length} passages; split the document` }, { status: 413 });
75 }
76
77 const embedded = await Azion.AI.run(EMBEDDING_MODEL, {
78 input: passages,
79 encoding_format: 'float',
80 dimensions: DIMENSIONS,
81 });
82
83 // O DELETE faz uma segunda execução para a mesma key substituir as linhas dela em vez de somar a elas.
84 const statements = [`DELETE FROM passages WHERE source = ${sqlText(key)};`];
85 for (const item of embedded.data) {
86 statements.push(
87 `INSERT INTO passages (source, content, embedding) VALUES (${sqlText(key)}, ${sqlText(passages[item.index])}, vector('[${item.embedding.join(',')}]'));`,
88 );
89 }
90 try {
91 await writeRows(statements);
92 } catch (error) {
93 console.log(error.message);
94 return Response.json({ error: 'The passages were not stored' }, { status: 502 });
95 }
96 return Response.json({ key, passages: passages.length });
97 },
98};

O código aplica quatro decisões:

  • Um documento por requisição. Uma leitura, uma chamada ao modelo e uma escrita limitam o trabalho de cada invocação. Uma function pode usar 2 segundos de tempo de CPU e 50 chamadas fetch() de saída por invocação.
  • No máximo 99 trechos por documento. O DELETE e 99 instruções INSERT somam 100 instruções, e uma chamada com 100 instruções dá certo. Um documento mais longo responde 413, então divida-o em dois arquivos.
  • A largura é uma única constante. DIMENSIONS define a requisição e precisa ser igual à largura F32_BLOB da coluna. Uma pergunta só é comparável a um trecho quando o mesmo modelo produziu os dois vetores na mesma largura.
  • Uma key ausente responde 404. get lança StorageError: Object not found para uma key que não guarda nenhum objeto, e Bucket not found para um bucket que a conta não tem.

Com azion dev, Azion.AI é undefined e azion:storage lê o disco local, então faça o deploy da function, como mostra Faça o deploy de uma function com a Azion CLI, e teste-a lá. Depois envie um documento:

Shell
01curl -X POST 'https://www.example.com/?key=<object-key>' \
02 -H 'Authorization: Bearer <ingest-secret>'

A function responde com a key e o número de trechos que armazenou, como {"key":"<object-key>","passages":3}. Uma requisição sem o header Authorization responde 401. A tabela guarda uma linha por trecho do documento, cada uma com o seu vetor.

Confirme que os trechos trazem vetores

Para contar as linhas do documento que guardam um vetor, envie um SELECT ao endpoint de consulta:

Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/sql/databases/<database-id>/query \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token <personal-token>' \
05 --header 'Content-Type: application/json' \
06 --data '{"statements":["SELECT COUNT(*) AS passages FROM passages WHERE source = '\''<object-key>'\'' AND embedding IS NOT NULL;"]}'

A única entrada em data traz results, cuja única linha guarda o número que a function retornou:

{"state":"executed","data":[{"results":{"columns":["passages"],"rows":[[3]],...}}]}

Cada trecho do documento traz um vetor, e vector_top_k em passages_idx pode retorná-lo. Um vetor de consulta também precisa vir de Qwen/Qwen3-Embedding-4B em 1.024 dimensões.

Próximos passos

Vector searchConsulte os trechos com vector_top_k e leia as funções de distância e os limites do índice.Qwen3 Embedding 4BO id do modelo, as larguras que ele retorna e o seu tamanho de contexto.Grave linhas no SQL Database a partir de uma functionArmazene as credenciais do banco de dados e verifique o resultado de cada instrução que uma function envia.Crie e execute assistentes de IA para suporte ao clienteUm assistente que ingere um bucket de documentação dessa forma e responde perguntas a partir dos trechos.