Scarica ed estrai il pacchetto Demo Python.
Il pacchetto contiene gli script e la configurazione utilizzati per dimostrare la gestione delle raccolte, l'elaborazione dei documenti, l'inferenza e le operazioni API correlate.
Ultimo aggiornamento il
29 set 2026
Esegui, ispeziona e adatta un'implementazione Python funzionante dei flussi di lavoro API Knowledge Base più comuni.
La demo Python fornisce un punto di partenza funzionale per lo sviluppo di applicazioni.Utilizza il flusso di lavoro completo per vedere in azione la creazione delle raccolte, l'elaborazione dei documenti e l'inferenza IA, quindi esplora i singoli script per operazioni specifiche di raccolta e inferenza.
Prima di iniziare
Assicurati di avere:
- Accesso all'API Knowledge Base.
- Le credenziali necessarie per autenticare l'applicazione.
- Python 3.7 o versione successiva. È consigliato Python 3.11 o versione successiva.
- Un PDF da utilizzare per il flusso di lavoro demo completo.
Se non hai configurato l'accesso API, consulta Configurare l'accesso API Knowledge Base.
Scarica e configura il Demo Python
Crea un ambiente virtuale:
python3 -m venv venv
Attiva l'ambiente:
- Su macOS o Linux:
source venv/bin/activate - Su Windows:
venv\Scripts\activate
Installa le dipendenze:
pip install --upgrade pip
pip install -e .
Aggiungi le credenziali API necessarie e la configurazione del servizio a config.yaml.
Passa alla sottocartella python prima di eseguire gli script di esempio.
La demo utilizza requests, pyyaml e tqdm.Le credenziali sono archiviate in config.yaml e i token di autenticazione sono gestiti automaticamente.
Non eseguire il commit dei file config.yaml o .token generati nel controllo del codice sorgente.
Esegui il flusso di lavoro completo
Esegui:
python knowledgebase.py
Per utilizzare un PDF specifico:
python knowledgebase.py --document=<percorso-del-pdf>
La demo:
- Esegue l'autenticazione con le API.
- Crea una raccolta denominata demo-collection.
- Carica un PDF.
- Monitora il documento fino al completamento dell'indicizzazione.
- Esegue una richiesta di inferenza sul documento elaborato.
Il caricamento e l'indicizzazione sono parti distinte dell'acquisizione dei documenti. L'indicizzazione estrae il contenuto del documento e lo rende disponibile per le operazioni di IA.
Se non specifichi un PDF, la demo ne seleziona uno dalla directory documents del pacchetto. L'elaborazione del documento va in timeout dopo cinque minuti se non raggiunge uno stato completo.
Nota
Il flusso di lavoro completo crea una raccolta denominata demo-collection e carica un PDF al suo interno. La demo non elimina la raccolta o il documento caricato al termine del flusso di lavoro.
Esplora le operazioni delle raccolte
Dopo aver eseguito il flusso di lavoro completo, utilizza script individuali per esplorare operazioni API specifiche.
Crea una raccolta
python collection.py --action create --name <collection-name>
I nomi delle raccolte possono contenere fino a 255 caratteri.
Elenco delle raccolte
python collection.py --action list
Scegli se elencare le raccolte create da te, condivise da te o condivise da altri quando richiesto.
Condividi una raccolta
python collection.py --action share --collection-id <collection-id>
Inserisci gli indirizzi e-mail che dovrebbero ricevere l'accesso in lettura o scrittura quando richiesto.
Carica documenti
python collection.py --action upload --collection-id <collection-id> --path=<percorso-al-file-o-directory>
Lo script può caricare un singolo file o documenti da una directory specificata.
Elenca documenti in una raccolta
python collection.py --action get_documents --collection-id <collection-id>
Controlla lo stato di elaborazione del documento
python collection.py --action get_status --document-id <document-id>
La demo fornisce queste operazioni come esempi autonomi che puoi ispezionare e adattare indipendentemente dal flusso di lavoro completo.
Esplora le operazioni di inferenza
Gli esempi di inferenza richiedono un ID della raccolta e un ID del documento.Utilizza gli Script di raccolta per identificarli:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
Risposta alle domande
Elenca le tue raccolte e documenti, quindi esegui l'esempio di domande e risposte:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --questionAnswer
Inserisci l'ID della raccolta, l'ID del documento e la domanda quando richiesto.
Riassunto del documento
Identifica la raccolta e il documento, quindi esegui l'esempio di riassunto:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --summarize
Inserisci l'ID della raccolta e l'ID del documento quando richiesto.
Ricerca contestuale
Identifica la raccolta e il documento, quindi esegui l'esempio di ricerca contestuale:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --context-search
Inserisci l'ID della raccolta, l'ID del documento e il testo di ricerca quando richiesto.
Estrazione delle proprietà
Identifica la raccolta e il documento, quindi esegui l'esempio di estrazione:
python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --extract
Inserisci l'ID raccolta, l'ID documento, il nome della proprietà, il prompt di estrazione, il tipo di dati e la descrizione facoltativa quando richiesti.
Continua a sviluppare con l'API
La demo Python fornisce modelli di implementazione funzionanti piuttosto che documentazione API completa.
Usa Introduzione all'API Knowledge Base per comprendere il modello delle risorse API, il ciclo di vita dei documenti, il comportamento dell'inferenza e la gestione delle risposte.
Usa il riferimento API Knowledge Base quando hai bisogno di percorsi endpoint correnti, parametri, schemi di richiesta e risposta e informazioni sullo stato.
Risoluzione dei problemi
La demo scrive informazioni diagnostiche dettagliate in:
logs/knowledgebase-demo.log
Il file di registro registra informazioni a livello DEBUG, mentre la console visualizza messaggi di livello WARNING e superiori.
Se un'operazione non riesce:
- Rivedi logs/kinowledgebase-demo.log per i dettagli di richiesta e autenticazione.
- Verifica le impostazioni in config.yaml.
- Conferma che il PDF che stai utilizzando esista e sia accessibile.
- Conferma che l'applicazione stia utilizzando l'endpoint di servizio appropriato per la tua organizzazione.
- Conferma che l'identità autenticata abbia accesso alla risorsa richiesta.
- Per errori API, conserva l'X-Request-ID restituito nelle intestazioni di risposta quando disponibile.Il supporto può utilizzare questo identificatore per tracciare la richiesta.
Considerazioni di implementazione
- Il flusso di lavoro completo accetta file PDF.
- La demo gestisce i token di autenticazione dopo aver configurato l'accesso API.
- Le operazioni API utilizzano le autorizzazioni disponibili per l'identità autenticata.
- Il pacchetto sorgente include funzionalità di rilevamento endpoint regionali, ma i valori endpoint di produzione dovrebbero provenire dalla documentazione API Knowledge Base corrente piuttosto che dai valori legacy inclusi con la demo.
