L'API supporta flussi di lavoro per gestire raccolte e documenti, elaborare contenuti e applicare funzionalità IA come risposta alle domande, riassunto, ricerca ed estrazione strutturata. Usa questa pagina per comprendere come questi elementi lavorano insieme, quindi consulta il riferimento API per i dettagli di implementazione a livello di endpoint.
Assicurati di avere:
Se non hai configurato l'accesso API, consulta Configura accesso API del Knowledge Base.
Un tipico flusso di lavoro API del Knowledge Base segue questa sequenza:
Autentica → Raccolta → Documento → Indice → Inferenza → Risposta
Una raccolta definisce il dominio di conoscenza con cui lavora l'applicazione. Quando crei una raccolta, la risposta include il suo namespace univoco, che usi nelle operazioni successive.
Esempio:
{
"namespace": "<collection-namespace>",
"name": "example-collection"
}
Conserva il namespace della raccolta per le richieste di documenti e inferenza.
I documenti vengono caricati nelle raccolte e viene loro assegnato un identificatore documento univoco.
Una risposta di caricamento identifica il documento così la tua applicazione può tracciare l'elaborazione e farvi riferimento in richieste successive.
{
"document_id": "<document-id>",
"document_name": "example.pdf"
}
Caricare un documento e indicizzarlo sono fasi separate.
Il caricamento trasferisce il file al Knowledge Base. L'indicizzazione estrae i suoi contenuti ed elabora quei contenuti per l'uso da parte delle operazioni IA.
L'applicazione dovrebbe confermare che l'elaborazione sia completata prima di inviare richieste di inferenza sul documento.
Le operazioni di inferenza applicano le funzionalità IA di Knowledge Base ai contenuti elaborati.
Le operazioni disponibili includono:
Utilizza il riferimento API per determinare l'endpoint e lo schema di richiesta per l'operazione che vuoi eseguire.
Le risposte di inferenza restituiscono il risultato generato e possono includere informazioni di attribuzione a supporto.
A seconda dell'operazione, i dati di attribuzione possono identificare il contenuto di origine, la pagina e le coordinate associate al risultato.L'applicazione determina come presentare tali informazioni all'utente.
Il flusso di lavoro dell'applicazione più semplice consiste nel creare una raccolta, aggiungere un documento, attendere l'elaborazione e quindi eseguire un'operazione di inferenza.
Crea la raccolta che conterrà i documenti di origine per l'applicazione.
Conserva il namespace restituito nella risposta:
collection_namespace = <returned-namespace>
Utilizzerai questo valore quando aggiungerai documenti e richiamerai operazioni nella raccolta.
Carica un documento nella raccolta e conserva l'ID documento restituito:
document_id = <id-documento-restituito>
L'ID del documento identifica il documento caricato indipendentemente dal nome del file.
Avvia l'operazione di indicizzazione richiesta, quindi controlla lo stato del documento fino al completamento dell'elaborazione.
Non dare per scontato che un caricamento riuscito significhi che il documento è pronto per le operazioni di IA.
Un flusso di applicazione tipico è:
Carica il documento
↓
Avvia l'indicizzazione
↓
Controlla lo stato dell'elaborazione
↓
Completato
Se l'elaborazione fallisce, risolvi il problema di elaborazione del documento prima di inviare una richiesta di inferenza.
Una volta completata l'elaborazione, invia il namespace della raccolta, l'ID del documento e qualsiasi input specifico dell'operazione richiesto dall'endpoint.
Ad esempio, una richiesta di domanda-risposta fornisce concettualmente:
Raccolta: <collection-namespace>
Documento: <document-id>
Domanda: Quali sono i risultati principali?
Utilizza il riferimento API per lo schema effettivo della richiesta.
Utilizza la risposta restituita o i dati estratti nella tua applicazione.
Se la risposta include informazioni di attribuzione, puoi utilizzarle per collegare le informazioni generate al contenuto del documento di supporto.
Il ciclo di vita del documento influisce su quando la tua applicazione può utilizzare il contenuto caricato.
| Prova | Cosa succede | Azione dell'applicazione |
|---|---|---|
| Carica | Il file viene aggiunto a Knowledge Base e riceve un ID documento. | Conserva l'ID del documento. |
| Indicizzazione | Il contenuto viene estratto ed elaborato per l'uso con l'IA. | Monitora lo stato del documento. |
| Completa | Il contenuto elaborato è disponibile per l'inferenza. | Invia richieste IA. |
| Non riuscito | Elaborazione non completata correttamente. | Risolvi l'errore prima di continuare. |
Questa distinzione è particolarmente importante per i flussi di lavoro automatizzati.Un'applicazione dovrebbe controllare lo stato di elaborazione piuttosto che inviare immediatamente una richiesta di inferenza dopo il caricamento.
Scegli un'operazione in base a quello che la tua applicazione deve fare con il contenuto di origine.
Utilizza Q&A per inviare domande in linguaggio naturale sul contenuto della raccolta o del documento.
L'API fornisce sia conversazioni domanda e risposta in flusso che non in flusso.
Il Q&A in streaming restituisce la risposta in modo incrementale man mano che viene generata.Usale quando l'interfaccia deve visualizzare il contenuto generato progressivamente.
Le conversazioni domanda e risposta in flusso supportano anche il controllo dell'applicazione delle istruzioni personalizzate alla richiesta. Puoi anche controllare se il ragionamento viene generato per una risposta domanda e risposta in flusso.
Le conversazioni domanda e risposta non in flusso attendono il completamento della generazione e restituiscono la risposta finita. Usale quando l'App non deve visualizzare un output parziale.
Usa il riepilogo per generare una rappresentazione condensata del contenuto del documento.
Il riferimento API definisce i requisiti di richiesta attuali e gli input supportati.
Usa la ricerca del contesto per recuperare contenuto rilevante per il testo di ricerca specificato.
Questo può aiutare le applicazioni a identificare materiale di origine rilevante senza generare una risposta colloquiale.
Usa l'estrazione quando l'App deve estrarre valori strutturati dal contenuto del documento.
Una definizione di estrazione può identificare informazioni come:
Nome proprietà: contract_value
Tipo: integer
Descrizione: Valore del contratto dell'accordo
Prompt: Estrai il valore di contratto più alto in dollari.
Il risultato restituito può includere il valore estratto, informazioni sul livello di attendibilità e l'attribuzione dell'origine.
L'API fornisce diversi modi per determinare quale contenuto partecipa a una richiesta.
Usa identificatori di raccolta e documento per definire il contenuto primario disponibile per un'operazione.
I tag sono associati ai documenti piuttosto che alle raccolte.
I tag dei documenti sono disponibili solo tramite l'API knowledge base e non sono esposti nell'interfaccia Utente normale.
Puoi usare i tag con operazioni supportate per filtrare i documenti considerati per una richiesta. Ad esempio, un'applicazione potrebbe assegnare un tag a un gruppo di documenti come documenti finanziari e limitare una domanda ai documenti che portano quel tag.
Gli allegati sono separati dai documenti della raccolta.
L'aggiunta di un allegato a una conversazione non aggiunge quel file alla raccolta.L'allegato può comunque contribuire al contesto di una risposta generata, insieme al contenuto della raccolta e alla cronologia della chat.
Usa gli endpoint degli allegati quando l'applicazione ha bisogno di contenuti temporanei o specifici della conversazione senza aggiungerli permanentemente a una raccolta.
Le risposte di inferenza possono includere informazioni di attribuzione che collegano l'output generato al contenuto di origine di supporto.
I dati di attribuzione possono includere informazioni come:
L'API fornisce queste informazioni sotto forma di dati.L'applicazione è responsabile di decidere come presentarle.
Ad esempio, un'applicazione può utilizzare le coordinate restituite per creare un'esperienza che evidenzia le origini e identifica la posizione che supporta una risposta generata.
Le operazioni API utilizzano le autorizzazioni disponibili per l'identità autenticata.
Una richiesta può fallire se l'identità autenticata non ha accesso alla raccolta, al documento o all'operazione richiesta.
Durante la risoluzione dei problemi:
L'X-Request-ID identifica la richiesta attraverso i servizi Knowledge Base e può aiutare il Supporto a indagare su una richiesta non riuscita.
Usa la demo Python quando desideri esempi funzionanti che dimostrino questi concetti in un'applicazione.
Introduzione alla demo Python di Knowledge Base
Usa il riferimento API quando sei pronto a implementare un'operazione specifica.
