Baixe e extraia o pacote de Demonstração em Python.
O pacote contém os scripts e a configuração usados para demonstrar o gerenciamento de coleções, o processamento de documentos, a inferência e as operações de API relacionadas.
Última atualização em
08/10/2026
Execute, inspecione e adapte uma implementação Python funcional de fluxos de trabalho comuns da API da Knowledge Base.
A Demonstração em Python fornece um ponto de partida funcional para o desenvolvimento de aplicativos. Use o fluxo de trabalho completo para ver a criação de coleções, o processamento de documentos e a inferência de IA funcionando juntos, depois explore scripts individuais para operações específicas de coleção e inferência.
Antes de começar
Verifique se você tem:
- Acesso à API da Knowledge Base.
- As credenciais necessárias para autenticar seu aplicativo.
- Python 3.7 ou posterior. Python 3.11 ou posterior é recomendado.
- Um PDF que você pode usar para o fluxo de trabalho completo da demonstração.
Se você não configurou o acesso à API, consulte Configurar acesso à API da Knowledge Base.
Baixar e configurar a Demonstração em Python
Crie um ambiente virtual:
python3 -m venv venv
Ative o ambiente:
- No macOS ou Linux:
source venv/bin/activate - No Windows:
venv\Scripts\activate
Instale as dependências:
pip install --upgrade pip
pip install -e .
Adicione as credenciais de API necessárias e a configuração de serviço a config.yaml.
Altere para a subpasta python antes de executar os scripts de exemplo.
A demonstração usa requests, pyyaml e tqdm. As credenciais são armazenadas em config.yaml, e os tokens de autenticação são gerenciados automaticamente.
Não confirme os arquivos config.yaml ou .token gerados no controle de origem.
Executar o fluxo de trabalho completo
Executar:
python knowledgebase.py
Para usar um PDF específico:
python knowledgebase.py --document=<path-to-pdf>
A demonstração:
- Autentica com a API.
- Cria uma coleção chamada demo-collection.
- Faz upload de um PDF.
- Monitora o documento até que a indexação seja concluída.
- Executa uma solicitação de inferência no documento processado.
Upload e indexação são partes distintas da ingestão de documentos. A indexação extrai o conteúdo do documento e o disponibiliza para operações de IA.
Se você não especificar um PDF, a demonstração selecionará um do diretório documents do pacote. O processamento de documentos expira após cinco minutos se não atingir um estado completo.
Nota
O fluxo de trabalho completo cria uma coleção chamada demo-collection e faz upload de um PDF para ela. A demonstração não exclui a coleção ou o documento carregado quando o fluxo de trabalho termina.
Explorar operações de coleção
Após executar o fluxo de trabalho completo, use scripts individuais para explorar operações específicas da API.
Criar uma coleção
python collection.py --action create --name <collection-name>
Os nomes das coleções podem conter até 255 caracteres.
Listar coleções
python collection.py --action list
Escolha se deseja listar coleções criadas por você, compartilhadas por você ou compartilhadas por outras pessoas quando solicitado.
Compartilhar uma coleção
python collection.py --action share --collection-id <collection-id>
Insira os endereços de email que devem receber acesso de leitura ou gravação quando solicitado.
Fazer upload de documentos
python collection.py --action upload --collection-id <collection-id> --path=<path-to-file-or-directory>
O script pode fazer upload de um único arquivo ou documentos de um diretório especificado.
Listar documentos em uma coleção
python collection.py --action get_documents --collection-id <collection-id>
Verificar status de processamento do documento
python collection.py --action get_status --document-id <document-id>
A demonstração fornece essas operações como exemplos independentes que você pode inspecionar e adaptar independentemente do fluxo de trabalho completo.
Explorar operações de inferência
Os exemplos de inferência requerem uma ID de coleção e uma ID de documento. Use os scripts de coleção para identificá-los:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
Perguntas e respostas
Liste suas coleções e documentos e, em seguida, execute o exemplo de perguntas e respostas:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --questionAnswer
Insira a ID da coleção, a ID do documento e a pergunta quando solicitado.
Resumo de documento
Identifique a coleção e o documento e, em seguida, execute o exemplo de resumo:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --summarize
Insira a ID da coleção e a ID do documento quando solicitado.
Pesquisa contextual
Identifique a coleção e o documento e, em seguida, execute o exemplo de pesquisa contextual:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --context-search
Insira a ID da coleção, a ID do documento e o texto de pesquisa quando solicitado.
Extração de propriedades
Identifique a coleção e o documento e, em seguida, execute o exemplo de extração:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --extract
Insira a ID da coleção, a ID do documento, o nome da propriedade, o prompt de extração, o tipo de dados e a descrição opcional quando solicitado.
Continuar criando com a API
A demonstração em Python apresenta padrões de implementação funcionais, e não uma documentação completa da API.
Use Começar com a API da Knowledge Base para entender o modelo de recurso da API, o ciclo de vida do documento, o comportamento de inferência e o manuseio de resposta.
Use a referência da API da Knowledge Base quando precisar de caminhos de ponto de acesso, parâmetros, esquemas de solicitação e resposta e informações de status atuais.
Solução de problemas
A demonstração grava informações de diagnóstico detalhadas em:
logs/knowledgebase-demo.log
O arquivo de log registra informações de nível DEBUG, enquanto o console exibe mensagens de nível WARNING e superior.
Se uma operação falhar:
- Revise logs/kinowledgebase-demo.log para obter detalhes de solicitação e autenticação.
- Verifique as configurações em config.yaml.
- Confirme que o PDF que você está usando existe e está acessível.
- Confirme que o aplicativo está usando o ponto de acesso de serviço apropriado para sua organização.
- Confirme que a identidade autenticada tem acesso ao recurso solicitado.
- Para falhas da API, mantenha o identificador X-Request-ID retornado nos cabeçalhos de resposta quando disponível. O suporte pode usar esse identificador para rastrear a solicitação.
Considerações de implementação
- O fluxo de trabalho completo aceita arquivos PDF.
- A demonstração gerencia tokens de autenticação após o acesso à API ser configurado.
- As operações da API usam as permissões disponíveis para a identidade autenticada.
- O pacote de origem inclui funcionalidade de descoberta de ponto de acesso regional, mas os valores de ponto de acesso de produção devem vir da documentação atual da API da Knowledge Base, não de valores legados incluídos com a demonstração.
