This page is not yet available in English. Read it in Portuguese

Skip to content

Sua primeira base no Knowledge: do documento à busca pela API

Equipe AIUBYEngenharia de plataforma

AIUBY Knowledge + busca pela API

O AIUBY Knowledge guarda os documentos de um workspace e responde buscas devolvendo o trecho e de onde ele veio. Este texto vai do primeiro arquivo enviado até a primeira busca por chave de API, com os números que definem o que cabe. A referência está em Knowledge, na documentação.

#O que entra numa base

O envio é feito pela área do cliente, em Conhecimento, ou pela API, com uma chave de envio. Cada documento vai para uma base do workspace e guarda as versões: enviar de novo o mesmo documento, com conteúdo diferente, cria a versão seguinte.

FormatoTamanho máximo
Texto e Markdown5 MB
PDF com texto20 MB
CSV2 MB, até 20.000 linhas e 60 colunas
  • PDF escaneado não entra: não há leitura de imagem. Um PDF sem texto é recusado no envio, não indexado pela metade.
  • Cada workspace pode ter até 20 documentos na fila de indexação ao mesmo tempo. Acima disso, um envio novo é recusado até a fila andar.

Pela API, com uma chave que tenha o escopo knowledge:write:

bash
curl -sS "https://aiuby.com/api/platform/knowledge/bases" -H "Authorization: Bearer $AIUBY_TOKEN"
curl -sS -X POST "https://aiuby.com/api/platform/knowledge/documents" \
  -H "Authorization: Bearer $AIUBY_TOKEN" \
  -F "baseId=$BASE_ID" -F "file=@politica-de-devolucao.md;type=text/markdown"

#Do arquivo ao trecho pesquisável

Depois do envio, um processo em segundo plano prepara o documento para a busca:

  • Corta em trechos. Cada trecho tem até 1.200 caracteres, com 150 de sobreposição com o anterior, para uma frase que cai na divisa não ficar sem contexto. O corte procura um fim de parágrafo ou de frase antes de cortar no meio.
  • Indexa de duas formas. Pelo texto, em português, e pelo significado, com um modelo de embeddings. A busca usa as duas e junta os resultados.
  • Troca a versão por inteiro. Quando a versão nova termina de indexar, o conteúdo da anterior é apagado. Substituir um arquivo para tirar um dado tira o dado.

O CSV tem tratamento próprio: as linhas são agrupadas em blocos que repetem o cabeçalho, para cada trecho continuar dizendo a que coluna cada valor pertence.

#Buscar pela API

Crie uma chave com o escopo "Buscar no Knowledge" (knowledge:read), como descrito em Chaves de API e escopos. A consulta tem até 2.000 caracteres e o limite de resultados é 20.

bash
curl -sS -X POST "https://aiuby.com/api/platform/knowledge/search" \
  -H "Authorization: Bearer $AIUBY_TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"prazo de devolução","limit":5}'

Cada resultado traz o trecho e a origem dele:

json
{
  "results": [
    {
      "chunkId": "...",
      "documentId": "...",
      "title": "Política de devolução",
      "baseName": "Atendimento",
      "version": 3,
      "ordinal": 2,
      "content": "O prazo de devolução é de ...",
      "score": 0.82
    }
  ]
}
  • title, baseName e version dizem de qual documento, de qual base e de qual versão o trecho saiu. É o que permite mostrar a fonte junto da resposta.
  • ordinal é a posição do trecho dentro do documento.
  • A pergunta pode ser em linguagem natural. Na busca por texto os termos são ligados por "ou": uma pergunta inteira não precisa ter todas as palavras no documento.

#Quem vê o quê

  • A busca só enxerga documentos do workspace da chave. Outro workspace e outra organização não aparecem, nem por erro.
  • Cada documento tem permissão própria. Um documento restrito a determinadas pessoas fica fora do resultado de uma busca feita por chave de API.
  • O filtro é feito no banco, não no código da busca. Como isso funciona está em Como uma organização não enxerga os dados de outra.

Nota

O conteúdo de um documento é tratado como dado, nunca como instrução. Um texto dentro de um arquivo dizendo "ignore as regras" não muda o que um agente pode fazer.

#O que consome saldo

Gerar embeddings é chamar um modelo, então a indexação e a busca passam pelo mesmo controle de gasto das outras chamadas de IA: orçamento do workspace, teto da organização e saldo.

  • Indexar um documento consome pouco, uma vez por versão.
  • Cada busca consome o equivalente a transformar a pergunta em vetor.
  • Sem saldo, ou sem conta de faturamento válida, a indexação de um documento novo falha com o motivo registrado e a busca é recusada. Nada é apagado: com a conta em dia, basta reindexar o documento.

O Knowledge também tem mensalidade por organização, que começa no primeiro uso. Os valores estão em Mensalidade por produto.

#Limites

Limite

Não há leitura de PDF escaneado nem de imagem. Pela API a chave envia documentos visíveis ao workspace inteiro; criar base, apagar e restringir a pessoas é só pela tela.

  • A busca devolve trechos, não uma resposta escrita. Quem redige a resposta com base neles é o Assistente ou um agente.
  • Não publicamos números de qualidade da busca: dependem dos seus documentos e das suas perguntas.
  • A chave de busca não lista nem baixa documentos inteiros.

Para usar a base dentro de um agente, o próximo passo é Agents, na documentação.