Sua primeira base no Knowledge: do documento à busca pela API
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.
| Formato | Tamanho máximo |
|---|---|
| Texto e Markdown | 5 MB |
| PDF com texto | 20 MB |
| CSV | 2 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:
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.
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:
{
"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,baseNameeversiondizem 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.


