API de Consultas em Bases de Conhecimento
A API de Consultas utiliza Recuperação Aumentada por Geração (RAG) para realizar buscas avançadas e precisas em bases de conhecimento já indexadas. Com isso, FAQs e agentes conseguem acessar rapidamente dados relevantes e obter respostas em linguagem natural, fundamentadas no conteúdo das bases de conhecimento, tornando o atendimento mais eficiente e assertivo.
Esta seção apresenta como utilizar a API de Consultas, incluindo os parâmetros necessários, formatos de resposta e possíveis erros.
Para começar a usar qualquer uma de nossas APIs, você precisará de uma chave de API válida. Se você ainda não tem uma, clique aqui para aprender como obter a sua. Guarde sua chave em um lugar seguro, pois ela será sua credencial para todas as requisições à API.
Além disso, você precisará de uma base de conhecimento já criada na plataforma Tech4AI. Se você ainda não tem uma, clique aqui para aprender como criar uma nova base.
Caso a base de conhecimento vá ser utilizada em um agente Tech4AI, você deverá seguir os passos para utilizar a base de conhecimento em actions.
Formato da Requisição
Endpoint
POST https://api.tech4ai.com/knowledge/query
Autenticação
A API utiliza autenticação via cabeçalho HTTP. Você deve incluir sua chave de API no cabeçalho x-client-key.
Payload da Requisição
O payload da requisição deve ser enviado em formato JSON com a estrutura abaixo:
{
"query": "string",
"knowledge_base_id": "uuid",
"top_k": 3
}
Parâmetros do Payload
| Parâmetro | Tipo | Obrigatório | Descrição | Default |
|---|---|---|---|---|
query | string | Sim | Pergunta ou consulta a ser realizada na base de conhecimento | - |
knowledge_base_id | string (uuid) | Sim | ID da base de conhecimento onde realizar a busca (formato UUID) | - |
top_k | integer/null | Não | Número de resultados que serão retornados. | Caso não seja informado, será utilizado o número setado na configuração da base de conhecimento, caso esse não tenha sido configurado, será usado o valor default de 3 |
Exemplo de Requisição
curl -X POST "https://api.tech4ai.com/knowledge/query" \
-H "Content-Type: application/json" \
-H "x-client-key: sua_chave_api_aqui" \
-d '{
"query": "Como configurar autenticação OAuth?",
"knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
"top_k": 5
}'
Formato da Resposta
Resposta de Sucesso (200)
A API retorna uma resposta em formato JSON com a estrutura abaixo:
{
"query_id": "uuid",
"status": "ok",
"chunks": {
"chunk_search_results": [
{
"id": "uuid",
"document_id": "uuid",
"score": 0.95,
"text": "conteúdo do chunk",
"metadata": {
"chunk_order": 1,
"document_type": "string",
"page_number": 20,
"semantic_rank": 0,
"full_text_rank": 0,
"associated_query": "query do usuário"
}
}
],
"score_threshold": 0.3
},
"answer": "Resposta gerada pelo LLM baseada na consulta e nos chunks encontrados"
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
query_id | string (uuid) | ID único da consulta |
status | string | Status da consulta, ok se a consulta retornou chunks relevantes, low_score se a consulta retornou chunks com score abaixo do score_threshold configurado. |
chunks | object | Objeto contendo os resultados da busca e configurações |
chunks.chunk_search_results[].id | string (uuid) | ID único do chunk no R2R |
chunks.chunk_search_results[].document_id | string (uuid) | ID do documento de origem |
chunks.chunk_search_results[].score | float | Pontuação de relevância do chunk (0-1) |
chunks.chunk_search_results[].text | string | Conteúdo textual do chunk |
chunks.chunk_search_results[].metadata | object | Metadados do chunk |
chunks.chunk_search_results[].metadata.chunk_order | integer | Ordem do chunk no documento |
chunks.chunk_search_results[].metadata.document_type | string | Tipo do documento (PDF, DOCX, etc.) |
chunks.chunk_search_results[].metadata.page_number | integer/null | Número da página onde o chunk está localizado, se foi possível extrair o número da página do documento será retornado, caso contrário será null |
chunks.chunk_search_results[].metadata.associated_query | string | Consulta associada ao chunk |
chunks.score_threshold | float | Limite mínimo de score para considerar um chunk relevante |
answer | string | Resposta gerada pela IA baseada na consulta e nos chunks encontrados |
Exemplo de Resposta de Sucesso
{
"query_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "ok",
"chunks": {
"chunk_search_results": [
{
"id": "456e7890-e89b-12d3-a456-426614174001",
"document_id": "789e1234-e89b-12d3-a456-426614174002",
"score": 0.95,
"text": "OAuth é um protocolo de autorização que permite aplicações obterem acesso limitado a contas de usuário. Para configurar OAuth, você precisa: 1) Registrar sua aplicação no provedor OAuth, 2) Configurar as URLs de redirecionamento...",
"metadata": {
"chunk_order": 2,
"document_type": "PDF",
"page_number": 5,
"semantic_rank": 1,
"full_text_rank": 1,
"associated_query": "Como configurar autenticação OAuth?"
}
}
],
"score_threshold": 0.7
},
"answer": "Para configurar autenticação OAuth, você precisa seguir os seguintes passos: 1) Registrar sua aplicação no provedor OAuth, 2) Configurar as URLs de redirecionamento, 3) Implementar o fluxo de autorização..."
}
Códigos de Erro
-
401 - Unauthorized: Chave de API inválida ou ausente
{
"detail": "Invalid client key"
} -
422 - Validation Error: Requisição inválida, como query vazia, uuid inválido, headers ausentes
{
"detail": [
{
"type": "value_error",
"loc": ["body", "query"],
"msg": "Query cannot be empty or contain only whitespace",
"input": ""
}
]
} -
404 - Not Found: Base de conhecimento não encontrada, não ativa, não publicada ou vazia
{
"detail": "Knowledge base not found"
}{
"detail": "Knowledge base is not active"
}{
"detail": "Knowledge base is not published"
}{
"detail": "Knowledge base is empty"
} -
500 - Internal Server Error: Erro interno do servidor
{
"detail": "Internal server error"
} -
504 - Gateway Timeout: Timeout na comunicação com R2R
{
"detail": "Request to R2R API timed out after 100 seconds"
}