Quando uma pergunta depende de contratos, manuais ou políticas internas, enviar tudo ao modelo em toda requisição é caro e pouco controlável. RAG, sigla de retrieval-augmented generation, acrescenta uma etapa de busca: a aplicação encontra trechos relacionados à pergunta, monta um contexto reduzido e só então pede ao modelo que responda.
Embeddings ajudam nessa busca ao representar textos como vetores. Textos próximos em significado tendem a produzir vetores que podem ser comparados por uma medida de similaridade. Isso não cria uma base de conhecimento por conta própria. Você ainda precisa preparar os documentos, armazenar vetores e metadados, consultar um índice, escolher trechos e avaliar se a resposta foi sustentada.
A Roteia expõe POST /v1/embeddings e uma categoria de modelos no catálogo. Ela não administra seu índice, não treina nem ajusta modelos de embedding e não visualiza vetores. Chunking, armazenamento, busca, filtros, montagem do prompt e interface de inspeção ficam na aplicação e nas ferramentas escolhidas pelo time.
Desenhe a resposta que precisa de fonte
Antes de dividir arquivos, selecione perguntas reais. Uma equipe de suporte pode precisar localizar prazo de cancelamento e citar a cláusula aplicável. Um técnico pode buscar o procedimento de manutenção para um equipamento específico. Em ambos os casos, a resposta útil inclui a conclusão e a origem; uma frase plausível sem documento não atende ao trabalho.
Defina o corpus autorizado para cada público. Manual público, contrato de um cliente e procedimento interno não devem compartilhar permissões só porque tratam de assuntos parecidos. O filtro de acesso precisa acontecer na busca, usando identidade e metadados do backend. Pedir ao modelo que ignore um trecho proibido depois de recuperá-lo já expôs a informação à chamada.
Escreva também o comportamento para ausência. Se nenhum trecho atingir o critério, a aplicação pode informar que não encontrou base suficiente e encaminhar para uma pessoa. RAG não obriga o modelo a responder; seu maior ganho costuma ser tornar a falta de evidência observável.
Prepare documentos com identidade e versão
Extraia texto preservando estrutura relevante: título, seção, página, data, produto e versão. Um vetor sem metadados pode recuperar uma frase, mas não permite filtrar contrato vigente nem montar uma citação compreensível. Guarde o identificador estável do documento e a posição do trecho para que a resposta leve a uma fonte revisável.
Limpeza não é apagar tudo que parece ruído. Cabeçalhos repetidos podem ser removidos; títulos e listas podem carregar contexto essencial. Em PDF escaneado, revise o OCR em números, datas e negações. Um erro inserido na extração vira uma recuperação fiel do dado errado.
Versione a ingestão. Quando uma política muda, marque a anterior como inativa ou limite sua validade em vez de apenas acrescentar o arquivo novo. Registre qual versão do texto, qual modelo de embedding e qual estratégia de divisão produziram cada vetor. Isso permite reindexar e explicar divergências.
- ID do documento e do trecho, sem depender do texto como chave.
- Origem, título, página ou seção para formar a citação.
- Tenant, público e regras de acesso aplicáveis à busca.
- Versão, data de vigência e estado ativo ou substituído.
Divida o texto pelo sentido da consulta
Chunks muito grandes misturam assuntos e devolvem contexto em excesso. Chunks curtos demais perdem condições, exceções e referências. O melhor tamanho depende do gênero do documento e da pergunta. Uma cláusula contratual pode precisar do caput e dos incisos; um catálogo técnico pode funcionar por item; uma conversa pode exigir turnos vizinhos.
Comece por limites naturais, como títulos e parágrafos, e aplique tamanho máximo depois. Uma pequena sobreposição ajuda quando uma ideia cruza a fronteira, mas repetições grandes ocupam índice e fazem a busca devolver cópias do mesmo trecho. Guarde um conjunto de perguntas com passagens esperadas para ajustar esse desenho.
Inclua no texto vetorizado somente metadados que realmente ajudam o significado. Colocar IDs aleatórios ou caminhos longos no conteúdo pode atrapalhar a representação; esses valores continuam úteis como campos de filtro. O texto enviado ao modelo de embedding e os metadados armazenados têm papéis diferentes.
Gere vetores com um contrato estável
Escolha no catálogo um modelo da categoria embeddings e envie texto ou uma lista de textos a /v1/embeddings. A rota aceita o ID e a entrada e devolve vetores com informação de uso. O modelo precisa ser o mesmo, ou comprovadamente compatível, na indexação dos documentos e na geração do vetor da consulta. Vetores de modelos ou dimensões diferentes não pertencem automaticamente ao mesmo espaço.
Envie lotes que respeitem limites e registre falhas por item. Se uma parte falhar, não marque o documento inteiro como indexado. Associe a cada vetor o hash ou a versão do trecho, o modelo e a dimensão recebida. Esse inventário é o que permite retomar ingestão sem duplicar conteúdo e planejar uma troca.
Dimensão menor pode reduzir armazenamento e custo de busca quando o modelo oferece esse parâmetro, mas a decisão precisa ser avaliada. Não corte vetores localmente por conveniência sem um contrato que preserve o comportamento. Meça recuperação no seu conjunto antes de alterar dimensão ou modelo.
curl https://api.roteia.ai/v1/embeddings \
-H "Authorization: Bearer $ROTEIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "COLE_UM_ID_DE_EMBEDDING_DO_CATALOGO",
"input": ["Trecho autorizado do documento"]
}'Busque, filtre e monte o contexto
Uma implementação comum usa cosine similarity para ordenar vetores guardados em um vector database. São escolhas de métrica e infraestrutura, não garantias de relevância; compare os resultados com perguntas e trechos esperados do seu domínio.
A aplicação gera o vetor da pergunta, consulta o índice vetorial e recebe candidatos com similaridade. Antes ou durante a busca, aplica filtros de tenant, idioma, produto e vigência. Depois pode remover duplicatas, combinar busca lexical e semântica ou reordenar resultados. Essas decisões acontecem fora do endpoint de embeddings.
Não trate o maior score como autorização automática para responder. A escala varia por modelo, distância e banco. Defina um critério usando perguntas rotuladas e observe falsos positivos. Em algumas tarefas, dois trechos complementares são necessários; em outras, resultados parecidos repetem a mesma passagem e desperdiçam contexto.
Monte o prompt separando instrução, pergunta e fontes. Numere os trechos e inclua os metadados de citação. Diga que a resposta deve se apoiar apenas no material fornecido e que a ausência de base precisa ser declarada. Essa instrução reduz improviso, mas a avaliação continua necessária: o modelo pode ignorar uma fonte ou atribuir a conclusão ao trecho errado.
Avalie recuperação e geração separadamente
Se a resposta está errada, primeiro confira se o trecho correto chegou ao prompt. Métricas de recuperação medem se passagens relevantes aparecem entre os primeiros resultados. Uma busca que falha não será consertada por um gerador mais eloquente. Se a fonte certa chegou, avalie fidelidade, cobertura da pergunta e qualidade da citação.
Monte um conjunto com pergunta, documentos permitidos, trechos esperados e resposta aceitável. Acrescente perguntas sem resposta, versões antigas, termos ambíguos e tentativas de acessar outro tenant. Revise exemplos reais de produção e transforme incidentes em casos de regressão. Uma nota única para o pipeline inteiro esconde a etapa que precisa mudar.
Meça custo e latência de ingestão separadamente da consulta. Indexar um documento pode gerar muitos embeddings uma vez; cada pergunta costuma gerar outro embedding, uma busca e uma geração. Alterar chunking muda quantidade de vetores, resultados recuperados e tokens enviados ao modelo de chat. Compare a conta completa.
Opere atualização, exclusão e rastreabilidade
Um índice envelhece. Defina como detectar documento alterado, remover trechos antigos e reprocessar somente o necessário. Exclusão no sistema de origem precisa chegar ao índice e a qualquer cache da aplicação. Guarde estados como pendente, indexado e falhou para não declarar uma base atualizada quando parte da ingestão parou.
Na resposta, registre IDs dos trechos recuperados, scores, filtros aplicados, modelo de embedding, modelo gerador e identificador da chamada. Evite gravar conteúdo sensível em logs amplos. O objetivo é reproduzir uma decisão técnica sem criar uma cópia desprotegida do corpus.
Comece pequeno: um corpus autorizado, algumas dezenas de perguntas e um caminho claro para dizer “não encontrei”. Só aumente a automação quando recuperação e citação se mantiverem estáveis. A API produz vetores e o catálogo ajuda a escolher o modelo; a qualidade do RAG nasce das decisões que conectam documento, índice, busca e resposta.
Dúvidas frequentes
RAG e embeddings são a mesma coisa?
Não. Embeddings são representações vetoriais usadas em uma possível etapa de busca. RAG é o fluxo que recupera conteúdo e o fornece ao modelo gerador. Também pode combinar busca lexical, filtros e reordenação.
A Roteia armazena meus vetores?
Não como parte da rota descrita. A Roteia devolve embeddings pela API; a aplicação escolhe e opera o banco ou índice onde vetores, documentos e metadados serão guardados.
Qual tamanho de chunk devo usar?
Não existe tamanho universal. Comece por limites naturais do documento, preserve o contexto necessário e avalie se os trechos esperados aparecem para perguntas reais. Ajuste tamanho e sobreposição com base nessa recuperação.
Posso trocar o modelo de embedding sem reindexar?
Em geral, não se deve misturar vetores de espaços diferentes. Planeje uma nova coleção, gere novamente os vetores e compare recuperação antes de migrar. Confirme também dimensão e contrato do modelo escolhido.
Como evitar que o RAG responda sem fonte?
Use limiar avaliado, trate ausência de recuperação, envie trechos identificados, peça citação e valide a resposta. Quando o risco for alto, mantenha revisão humana. Prompt sozinho não garante fidelidade.
Onde confirmar
Plataforma de terceiro muda de tela e de limite sem avisar. Confira na fonte oficial antes de tomar decisão baseada nesta página.