Responda perguntas a partir de uma tabela vetorial

Responda a uma pergunta a partir de uma function com os trechos mais próximos de uma tabela vetorial do SQL Database e um modelo de chat que os cita.

Última atualização

Ver como Markdown Configurar agente

Você responde a uma pergunta a partir de uma function: ela gera o embedding da pergunta com um modelo no AI Inference, recupera os trechos mais próximos de uma tabela vetorial do SQL Database com vector_top_k e pede a um modelo de chat que responda a partir deles e os cite. Os trechos vêm de documentos em um bucket do Object Storage, que uma segunda function na mesma aplicação ingere. Para o padrão geral de ingestão, consulte Gere embeddings de documentos em uma tabela vetorial com AI Inference.

Pré-requisitos

  • Uma aplicação e um workload que servem o seu domínio, com o Application Accelerator ativado, que o behavior Run Function exige. Para criá-los, consulte Primeiros passos com Applications.
  • SQL Database habilitado na conta. O produto está em Preview e não vem habilitado por padrão, então solicite acesso pelo Technical Support.
  • Uma tabela passages com um índice vetorial passages_idx para vetores de 1.024 dimensões. Para criá-los, consulte Crie a tabela vetorial.
  • Um bucket do Object Storage com workloads_access definido como read_only, que guarda os documentos como arquivos de texto UTF-8 ou Markdown. Para criar o bucket e enviar os arquivos, consulte Primeiros passos com Object Storage.
  • Um personal token com a permissão Edit SQL Database, para as chamadas ao banco de dados. Para criar um, consulte Gerencie personal tokens.
  • A Azion CLI, instalada e autorizada, para armazenar as variáveis de ambiente.

Os exemplos usam support-docs para o bucket, support-kb para o banco de dados, returns-policy.md para um documento dentro dele, /admin/ingest e /api/ask para os dois caminhos e www.example.com para o domínio. Substitua-os pelos seus valores.

Faça a ingestão dos documentos de um bucket

A function de ingestão transforma um documento em linhas de passages: ela lê o documento no bucket, o divide em trechos de até 1.500 caracteres, gera os embeddings de todos eles em uma chamada e os grava pela API da Azion, porque a conexão do runtime com um banco de dados é somente leitura. A rota grava no banco de dados, então ela recusa uma requisição sem o segredo de ingestão.

Para armazenar os quatro valores que a function lê, execute estes comandos com a Azion CLI. Uma key que contém token ou secret é armazenada como secret por padrão:

Shell
01azion create variables --key "AZION_TOKEN" --value "[TOKEN VALUE]"
02azion create variables --key "INGEST_SECRET" --value "<ingest-secret>"
03azion create variables --key "SQL_DATABASE_ID" --value "<database-id>" --secret false
04azion create variables --key "DOCS_BUCKET" --value "support-docs" --secret false

Crie as variáveis antes da function: uma function que já está em execução não lê um valor alterado até receber um novo deploy.

Crie uma function chamada support-ingest com este código:

JavaScript
01import Storage from "azion:storage";
02
03const EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-4B";
04const DIMENSIONS = 1024;
05const MAX_PASSAGE = 1500;
06const MAX_PASSAGES = 99;
07
08function split(text) {
09 const passages = [];
10 let current = "";
11 for (const paragraph of text.split(/\n\s*\n/)) {
12 const p = paragraph.trim();
13 if (!p) continue;
14 if (current && current.length + p.length > MAX_PASSAGE) {
15 passages.push(current);
16 current = "";
17 }
18 current = current ? current + "\n\n" + p : p;
19 }
20 if (current) passages.push(current);
21 return passages;
22}
23
24const quote = (value) => "'" + value.replaceAll("'", "''") + "'";
25
26export default {
27 async fetch(request, env, ctx) {
28 if (request.method !== "POST") {
29 return new Response("Method not allowed", { status: 405 });
30 }
31 if (request.headers.get("Authorization") !== `Bearer ${Azion.env.get("INGEST_SECRET")}`) {
32 return new Response("Unauthorized", { status: 401 });
33 }
34 const key = new URL(request.url).searchParams.get("key");
35 if (!key) {
36 return Response.json({ error: "key is required" }, { status: 400 });
37 }
38
39 const object = await new Storage(Azion.env.get("DOCS_BUCKET")).get(key);
40 const passages = split(new TextDecoder().decode(await object.arrayBuffer()));
41 if (passages.length === 0 || passages.length > MAX_PASSAGES) {
42 return Response.json({ error: `${passages.length} passages; split the document` }, { status: 413 });
43 }
44
45 const embedded = await Azion.AI.run(EMBEDDING_MODEL, {
46 "input": passages,
47 "encoding_format": "float",
48 "dimensions": DIMENSIONS
49 });
50
51 const statements = [`DELETE FROM passages WHERE source = ${quote(key)};`];
52 for (const item of embedded.data) {
53 statements.push(
54 `INSERT INTO passages (source, content, embedding) VALUES (${quote(key)}, ${quote(passages[item.index])}, vector('[${item.embedding.join(",")}]'));`
55 );
56 }
57
58 const result = await fetch(
59 `https://api.azion.com/v4/workspace/sql/databases/${Azion.env.get("SQL_DATABASE_ID")}/query`,
60 {
61 method: "POST",
62 headers: {
63 "Accept": "application/json",
64 "Authorization": `Token ${Azion.env.get("AZION_TOKEN")}`,
65 "Content-Type": "application/json"
66 },
67 body: JSON.stringify({ statements })
68 }
69 );
70 const body = await result.json();
71 const failed = (body.data ?? []).find((entry) => entry.error);
72 if (!result.ok || failed) {
73 return Response.json({ error: failed?.error ?? `SQL API answered ${result.status}` }, { status: 502 });
74 }
75 return Response.json({ key, passages: passages.length });
76 },
77};

Execute a function no caminho dela com estes valores, seguindo Primeiros passos com Functions:

  • Instância da function: support-ingest, sem Args.
  • Regra: uma regra de Request Phase chamada support - ingest, com o critério ${uri} starts with /admin/ingest e o behavior Run Function selecionando a instância support-ingest.

Para criar a regra no Azion Console ou pela API, consulte Adicione a regra que executa a função.

Um POST para /admin/ingest com o segredo e a key de um documento substitui os trechos desse documento em passages e responde com o número de trechos armazenados. O DELETE faz com que uma segunda ingestão da mesma key substitua as linhas dela em vez de duplicá-las.

Para fazer a ingestão do documento de exemplo:

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

A function responde com a key e o número de trechos que armazenou, como {"key":"returns-policy.md","passages":3}. Uma requisição sem o header Authorization responde 401. Para contar as linhas do documento pela API do SQL Database:

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 [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data '{"statements":["SELECT COUNT(*) FROM passages WHERE source = '\''returns-policy.md'\'' AND embedding IS NOT NULL;"]}'

A única entrada em data traz results, cuja única linha guarda o mesmo número que a ingestão retornou.

O caso de uso Criar e executar assistentes de IA para suporte ao cliente usa os valores deste exemplo.

Estas verificações confirmam o caso de uso Criar e executar assistentes de IA para suporte ao cliente.

Armazene o nome do banco de dados

A function abre o banco de dados pelo nome, por uma réplica de leitura.

Para armazenar o nome do banco de dados que a function abre, execute:

azion create variables --key "SQL_DATABASE_NAME" --value "support-kb" --secret false

A conta guarda a variável SQL_DATABASE_NAME, que a function lê com Azion.env.get().

O caso de uso Criar e executar assistentes de IA para suporte ao cliente usa os valores deste exemplo.

Crie a function do assistente

A function gera o embedding da pergunta com o mesmo modelo e a mesma largura dos trechos, recupera os quatro trechos mais próximos e os envia ao modelo de chat com as seis últimas mensagens de history e a pergunta. Ela grava uma linha de log "event":"answer" por resposta, registrando se a resposta cita um trecho.

Crie uma function chamada support-assistant com este código:

JavaScript
01const EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-4B";
02const CHAT_MODEL = "Qwen/Qwen3-30B-A3B-Instruct-2507-FP8";
03const DIMENSIONS = 1024;
04const TOP_K = 4;
05
06const SYSTEM_PROMPT =
07 "You answer customer questions using only the numbered passages in the user message. " +
08 "Cite every passage you use as [n]. If the passages do not contain the answer, " +
09 "say that you do not know and suggest contacting support.";
10
11async function retrieve(question) {
12 const embedded = await Azion.AI.run(EMBEDDING_MODEL, {
13 "input": question,
14 "encoding_format": "float",
15 "dimensions": DIMENSIONS
16 });
17 const vector = embedded.data[0].embedding.join(",");
18
19 const { Database } = Azion.Sql;
20 const connection = await Database.open(Azion.env.get("SQL_DATABASE_NAME"));
21 const rows = await connection.query(
22 `SELECT passages.source, passages.content FROM vector_top_k('passages_idx', vector('[${vector}]'), ${TOP_K}) JOIN passages ON passages.rowid = id;`
23 );
24
25 const passages = [];
26 let row = await rows.next();
27 while (row) {
28 passages.push({ source: row.getString(0), content: row.getString(1) });
29 row = await rows.next();
30 }
31 return passages;
32}
33
34export default {
35 async fetch(request, env, ctx) {
36 if (request.method !== "POST") {
37 return new Response("Method not allowed", { status: 405 });
38 }
39 const { question, history = [] } = await request.json();
40 if (typeof question !== "string" || question.trim() === "") {
41 return Response.json({ error: "question is required" }, { status: 400 });
42 }
43
44 const passages = await retrieve(question);
45 const context = passages
46 .map((p, i) => `[${i + 1}] (${p.source})\n${p.content}`)
47 .join("\n\n");
48
49 const modelResponse = await Azion.AI.run(CHAT_MODEL, {
50 "stream": false,
51 "max_tokens": 800,
52 "messages": [
53 { "role": "system", "content": SYSTEM_PROMPT },
54 ...history.slice(-6),
55 { "role": "user", "content": `Passages:\n${context}\n\nQuestion: ${question}` }
56 ]
57 });
58
59 const answer = modelResponse?.choices?.[0]?.message?.content ?? "";
60 const cited = /\[\d+\]/.test(answer);
61 console.log(JSON.stringify({ event: "answer", cited, passages: passages.length }));
62
63 return Response.json({
64 answer,
65 sources: passages.map((p, i) => ({ n: i + 1, source: p.source }))
66 });
67 },
68};

Para criar a function e a sua instância, siga Primeiros passos com Functions com o nome support-assistant e dê à instância o nome support-assistant, sem Args.

A aplicação tem uma instância support-assistant que responde a uma pergunta a partir dos trechos mais próximos dela.

O caso de uso Criar e executar assistentes de IA para suporte ao cliente usa os valores deste exemplo.

Execute a function no caminho

Crie uma regra de Request Phase como mostra Adicione a regra que executa a função, com o nome support - ask, o critério ${uri} is equal /api/ask e o behavior Run Function selecionando a instância support-assistant.

Um POST para /api/ask com uma pergunta responde com a resposta do modelo, que cita trechos como [n], e com o documento de onde veio cada trecho citado. Uma regra nova leva alguns minutos para se propagar.

Confirme que as respostas citam os documentos

Para fazer uma pergunta que o documento responde:

Shell
01curl -X POST https://www.example.com/api/ask \
02 -H 'Content-Type: application/json' \
03 -d '{"question":"How many days do I have to return an item?"}'

A resposta traz answer, com pelo menos uma citação [n], e sources, cujas entradas indicam returns-policy.md.

Faça uma pergunta que nenhum documento cobre, como What is the capital of France?. A resposta diz que o assistente não sabe e não traz nenhuma citação.

A function responde a partir dos trechos da tabela, e apenas deles.

Estas verificações confirmam o caso de uso Criar e executar assistentes de IA para suporte ao cliente.

Próximos passos

Vector searchA função vector_top_k, as funções de distância e os limites de um índice vetorial.Criar e executar assistentes de IA para suporte ao clienteO design a que esta function serve: o tamanho dos trechos, quantos são recuperados e o limite da resposta, com o motivo de cada um.