Skip to main content

Knowledge

O módulo Knowledge fornece um cliente simples para consultar as bases de conhecimento internas da Tech4.ai. Ele encapsula a chamada HTTP para o endpoint interno e retorna um objeto tipado com a resposta, incluindo a resposta gerada pelo LLM e os trechos (chunks) mais relevantes.

📋 Método Principal​

query(query, knowledge_base_id, top_k=3, rerank=False, extra_context=None)​

Realiza a consulta à base de conhecimento e retorna QueryResponse.

Parâmetros:

  • query (str): Consulta em linguagem natural
  • knowledge_base_id (UUID | str): ID da base de conhecimento a ser consultada
  • top_k (int): Quantidade de resultados a retornar (padrão: 3)

Retorno (QueryResponse):

  • query_id (UUID | None)
  • status (RetrieveStatus): OK ou LOW_SCORE
  • chunks (RetrieveResults):
    • chunk_search_results (List[ChunkSearchResult])
    • score_threshold (float)
  • answer (str): Resposta gerada pelo LLM (pode ser vazia quando LOW_SCORE)

📥 Exemplo de Entrada e Saída​

Entrada​

{
  "query": "O que é Sql"
}

Saída (exemplo real, resumida)​

{
  "query_id": "0c82f6e3-f990-4b65-87ff-e9302c25e58d",
  "status": "ok",
  "chunks": {
    "chunk_search_results": [
      {
        "id": "5a398b62-0dd5-5e2a-95cf-bd1ac4891014",
        "document_id": "f8888748-cb70-4909-bd1f-2fa5e5ea6629",
        "score": 0.5716894524282553,
        "text": "# Integração da linguagem SQL com as aplicações (parte 3)\n\n## SQL Estendida\n- Extensão da SQL criada para incluir estruturas procedurais à linguagem ...",
        "metadata": {
          "chunk_order": 9,
          "document_type": "pdf",
          "page_number": 10,
          "semantic_rank": null,
          "full_text_rank": null,
          "associated_query": "O que é Sql"
        }
      },
      {
        "id": "d2535bbd-dae4-5935-8ab5-93a31cb498b0",
        "document_id": "8914b5c0-f107-4977-8a11-3ac8b61e4ff5",
        "score": 0.5637222528457642,
        "text": "# Integração da linguagem SQL com as aplicações (parte 3)\n\n- SQL Estendida ...",
        "metadata": {
          "chunk_order": 9,
          "document_type": "pdf",
          "page_number": 10,
          "semantic_rank": null,
          "full_text_rank": null,
          "associated_query": "O que é Sql"
        }
      },
      {
        "id": "2208f7fc-bf13-5a76-b719-50b790c72c3f",
        "document_id": "65d8d169-5e1c-475a-b5a4-6c26e82a79aa",
        "score": 0.5490762264087075,
        "text": "# Comandos SQL\n- begin (begin transaction) ...",
        "metadata": {
          "chunk_order": 3,
          "document_type": "pdf",
          "page_number": 4,
          "semantic_rank": null,
          "full_text_rank": null,
          "associated_query": "O que é Sql"
        }
      }
    ],
    "score_threshold": 0.45
  },
  "answer": "Com base no contexto fornecido, 'SQL' pode se referir a: SQL Estendida (PL/SQL, PL/pgSQL, Transact-SQL) ... também menciona comandos de transação como begin, commit, rollback ..."
}

📝 Exemplo Prático​

Consultar base de conhecimento com formatação de resposta​


def consultar_base_de_conhecimento(consulta: str):
    """
    Consulta a base de conhecimento através da API de conhecimento
    """
    try:
        query_span = action_span.span("consulta na base", {"query": consulta})

        response = knowledge.query(
            query=consulta,
            knowledge_base_id=secrets["KNOWLEDGE_BASE_ID"],
        )

        query_span.end({"response": response.model_dump()})
        action_span.event("response", {"status": response.status, "ans": response.answer})

        # Compare sempre com o Enum, não com string
        if response.status != RetrieveStatus.OK or not response.answer:
            return ResponseToUser(
                message="Não encontrei informações específicas sobre sua consulta.",
                status=ResponseStatus.SUCCESS,  # SUCCESS para fluxo normal sem resposta específica
            )

        message = response.answer
        if response.chunks.chunk_search_results:
            sources_count = len(response.chunks.chunk_search_results)
            message += f"\n\n*Baseado em {sources_count} fonte(s) da base de conhecimento.*"

        return ResponseToUser(message=message, status=ResponseStatus.SUCCESS)

    except Exception as e:
        action_span.event("error", {"error": str(e)})
        return ResponseToUser(
            message=(
                "Peço desculpas, estamos enfrentando problemas técnicos no momento. "
                "Tente novamente em alguns instantes."
            ),
            status=ResponseStatus.ERROR,
            metadata={
                "error_type": "knowledge_api_error",
                "error_message": str(e),
            },
        )

💡 Dicas de Uso​

Melhores Práticas
  • Enum de status: compare com RetrieveStatus.OK em vez de strings
  • top_k: ajuste para balancear precisão e cobertura (3–5 costuma funcionar bem)

📊 Estruturas de Dados​

Enums e Classes Principais​

  • RetrieveStatus (Enum): OK, LOW_SCORE
  • ChunkMetadata: metadados do trecho (ordem, tipo de documento, página, ranks, query associada)
  • ChunkSearchResult: id, document_id, score, text, metadata
  • RetrieveResults: chunk_search_results (lista de ChunkSearchResult), score_threshold
  • RetrieveResponse: query_id, status, chunks
  • QueryResponse (extends RetrieveResponse): answer