Criar uma coleção
Crie a coleção que conterá os documentos de origem do aplicativo.
Mantenha o namespace retornado na resposta:
collection_namespace = <returned-namespace>
Você usará esse valor ao adicionar documentos e invocar operações na coleção.
Última atualização em
08/10/2026
Entenda como a API do Knowledge Base organiza conteúdo, processa documentos e executa operações de IA para que você possa criar aplicativos na plataforma.
A API oferece suporte a fluxos de trabalho para gerenciar coleções e documentos, processar conteúdo e aplicar recursos de IA, como respostas a perguntas, resumos, pesquisa e extração estruturada. Use esta página para entender como essas partes funcionam juntas e, em seguida, use a referência da API para obter detalhes de implementação no nível do ponto de acesso.
Antes de começar
Verifique se você tem:
- Acesso à Knowledge Base.
- Acesso à API configurado para seu aplicativo.
- Acesso a uma coleção ou permissão para criar uma.
- A referência da API da Knowledge Base disponível para as definições e os esquemas de ponto de acesso atuais.
Se você não configurou o acesso à API, consulte Configurar acesso à API da Knowledge Base.
Como a API funciona
Um fluxo de trabalho típico da API da Knowledge Base segue esta sequência:
Autenticação → Coleção → Documento → Índice → Inferência → Resposta
Coleção
Uma coleção define o domínio de conhecimento com o qual seu aplicativo trabalha. Quando você cria uma coleção, a resposta inclui seu namespace exclusivo, que você usa em operações subsequentes.
Por exemplo:
{
"namespace": "<collection-namespace>",
"name": "example-collection"
}
Retenha o namespace da coleção para solicitações de documento e inferência.
Documento
Os documentos são carregados para coleções e recebem identificadores únicos de documento.
Uma resposta de upload identifica o documento para que seu aplicativo possa acompanhar o processamento e referenciá-lo em solicitações posteriores.
{
"document_id": "<document-id>",
"document_name": "example.pdf"
}
Indexação
Fazer upload de um documento e indexá-lo são etapas separadas.
O upload transfere o arquivo para a Knowledge Base. A indexação extrai seu conteúdo e o processa para ser usado por operações de IA.
Seu aplicativo deve confirmar que o processamento foi concluído antes de enviar solicitações de inferência contra o documento.
Inferência
As operações de inferência aplicam recursos de IA da Knowledge Base a conteúdo processado.
As operações disponíveis incluem:
- Perguntas e respostas
- Resumo de documento
- Pesquisa contextual
- Extração de propriedades estruturadas
Use a referência da API para determinar o ponto de acesso e o esquema de solicitação para a operação que deseja executar.
Resposta
As respostas de inferência retornam o resultado gerado e podem incluir informações de atribuição de suporte.
Dependendo da operação, os dados de atribuição podem identificar o conteúdo de origem, a página e as coordenadas associadas ao resultado. O aplicativo determina como essas informações são apresentadas ao usuário.
Executar um fluxo de trabalho básico da API
O fluxo de trabalho de aplicativo mais simples é criar uma coleção, adicionar um documento, aguardar o processamento e executar uma operação de inferência.
Fazer upload de um documento
Faça upload de um documento para a coleção e retenha a ID do documento retornado:
document_id = <returned-document-id>
O ID do documento identifica o documento carregado independentemente do nome do arquivo.
Processar o documento
Inicie a operação de indexação necessária e verifique o status do documento até que o processamento seja concluído.
Não assuma que um upload bem-sucedido significa que o documento está pronto para operações de IA.
Um fluxo típico de aplicativo é:
Fazer upload do documento
↓
Iniciar indexação
↓
Verificar status do processamento
↓
Concluído
Se o processamento falhar, resolva o problema de processamento do documento antes de enviar uma solicitação de inferência.
Executar uma operação de inferência
Após a conclusão do processamento, envie o namespace da coleção, a ID do documento e qualquer entrada específica da operação exigida pelo ponto de acesso.
Por exemplo, uma solicitação de pergunta e resposta fornece conceitualmente:
Coleção: <collection-namespace>
Documento: <document-id>
Pergunta: Quais são as principais descobertas?
Use a referência da API para o esquema real da solicitação.
Processar a resposta
Use a resposta retornada ou os dados extraídos no seu aplicativo.
Se a resposta incluir informações de atribuição, você pode usá-las para conectar as informações geradas de volta ao conteúdo do documento de suporte.
Entender o processamento de documentos
O ciclo de vida do documento afeta quando o aplicativo pode usar o conteúdo carregado.
| Estágio | O que acontece | Ação do aplicativo |
|---|---|---|
| Carregar | O arquivo é adicionado à Knowledge Base e recebe uma ID de documento. | Mantenha o ID do documento. |
| Indexação | O conteúdo é extraído e processado para uso de IA. | Monitorar o status do documento. |
| Concluído | O conteúdo processado está disponível para inferência. | Enviar solicitações de IA. |
| Falhou | O processamento não foi concluído com sucesso. | Resolva a falha antes de continuar. |
Essa distinção é particularmente importante para fluxos de trabalho automatizados. Um aplicativo deve verificar o status de processamento em vez de enviar imediatamente uma solicitação de inferência após o upload.
Escolha uma operação de inferência
Escolha uma operação com base no que o aplicativo precisa fazer com o conteúdo de origem.
Perguntas e respostas
Use Perguntas e respostas para enviar perguntas em linguagem natural sobre o conteúdo da colação ou do documento.
A API fornece perguntas e respostas com e sem fluxo.
Perguntas e respostas com fluxo retorna a resposta incrementalmente conforme é gerada. Use-o quando sua interface deve exibir o conteúdo gerado progressivamente.
As Perguntas e respostas com fluxo também suportam o controle das Instruções personalizadas são aplicadas à solicitação. Você também pode controlar se o raciocínio é gerado para uma resposta de Perguntas e respostas em fluxo.
Perguntas e respostas sem fluxo aguarda a conclusão da geração e retorna a resposta final. Use quando o aplicativo não precisar exibir saída parcial.
Resumo
Use o resumo para gerar uma representação condensada do conteúdo do documento.
A referência da API define os requisitos de solicitação atuais e as entradas compatíveis.
Pesquisa contextual
Use a pesquisa de contexto para recuperar o conteúdo relevante ao texto de pesquisa especificado.
Isso pode ajudar os aplicativos a identificar material de origem relevante sem gerar uma resposta conversacional.
Extração de propriedades
Use a extração quando o aplicativo precisar de valores estruturados do conteúdo do documento.
Uma definição de extração pode identificar informações como:
Nome da propriedade: contract_value
Tipo: integer
Descrição: Valor do contrato do acordo
Prompt: Extraia o maior valor do acordo em dólares.
O resultado retornado pode incluir o valor extraído, as informações de confiança e a atribuição de origem.
Controlar o conteúdo usado por uma operação
A API fornece várias maneiras de determinar qual conteúdo participa de uma solicitação.
Coleções e documentos
Use identificadores de coleção e documento para definir o conteúdo principal disponível para uma operação.
Tags de documentos
As tags são associadas a documentos, não a coleções.
As tags de documentos estão disponíveis apenas por meio da API da Knowledge Base e não são expostas na interface do usuário padrão.
Você pode usar tags com operações compatíveis para filtrar os documentos considerados para uma solicitação. Por exemplo, um aplicativo pode marcar com tag um grupo de documentos como documentos financeiros e restringir uma pergunta a documentos que carreguem essa tag.
Anexos
Os anexos são separados dos documentos da coleção.
Adicionar um anexo a uma conversa não adiciona esse arquivo à coleção. O anexo ainda pode contribuir com contexto para uma resposta gerada, juntamente com o conteúdo da coleção e o histórico do chat.
Use pontos de acesso de anexo quando o aplicativo precisar de conteúdo temporário ou específico da conversa sem adicioná-lo permanentemente a uma coleção.
Trabalhar com dados de atribuição
As respostas de inferência podem incluir informações de atribuição que conectam a saída gerada ao conteúdo de origem de suporte.
Os dados de atribuição podem incluir informações como:
- Texto de apoio
- Informações do documento
- Número da página
- Coordenadas da página
A API fornece essas informações como dados. O aplicativo é responsável por decidir como apresentá-las.
Por exemplo, um aplicativo pode usar coordenadas retornadas para criar uma experiência de destaque de origem que identifica o local que apoia uma resposta gerada.
Lidar com falhas de acesso e solicitação
As operações da API usam as permissões disponíveis para a identidade autenticada.
Uma solicitação pode falhar se a identidade autenticada não tem acesso à coleção, ao documento ou à operação que está sendo solicitada.
Ao solucionar problemas:
- Revise o status HTTP retornado e a resposta.
- Confirme que a identidade autenticada pode acessar o recurso solicitado.
- Confirme que o processamento do documento foi concluído com sucesso antes de executar a inferência.
- Verifique se os identificadores fornecidos na solicitação estão corretos.
- Capture a X-Request-ID retornada nos cabeçalhos da resposta.
O X-Request-ID identifica a solicitação nos serviços do Knowledge Base e pode ajudar o Suporte a investigar uma solicitação com falha.
Considerações de implementação
- Uma única solicitação de upload suporta até 200 arquivos. Arquivos adicionais podem ser carregados através de solicitações subsequentes.
- O upload e a indexação são operações separadas.
- Os documentos devem atingir um estado de processamento concluído antes de serem usados para inferência.
- Os anexos são recursos independentes e não são adicionados automaticamente às coleções.
- Tags pertencem a documentos e podem ser usadas por operações compatíveis para filtrar conteúdo de origem.
- Use a referência da API como fonte confiável para endpoints, parâmetros, esquemas e operações compatíveis atuais.
Continuar desenvolvendo
Use a demonstração em Python quando desejar exemplos práticos que demonstrem esses conceitos em um aplicativo.
Começar a usar a Demonstração em Phyton da Knowledge Base
Use a referência da API quando estiver pronto para implementar uma operação específica.
