Crea una ricerca di contenuti AI con l'agente di Documenti

La ricerca di informazioni è uno degli usi più comuni dei modelli di intelligenza artificiale (IA) generativa. La creazione di un'interfaccia di ricerca conversazionale per i tuoi contenuti utilizzando l'IA consente agli utenti di porre domande specifiche e di ricevere risposte dirette.

Questo tutorial mostra come creare un'interfaccia di ricerca conversazionale basata sull'IA per i tuoi contenuti. Si basa su Agente Documenti, un progetto open source che utilizza l'API Google Gemini per creare un'interfaccia di ricerca con linguaggio naturale, senza addestrare un nuovo modello di IA o eseguire l'ottimizzazione del modello con i modelli Gemini. Ciò significa che puoi creare questa funzionalità di ricerca rapidamente e usarla per insiemi di contenuti di piccole e grandi dimensioni.

Per una panoramica video del progetto e su come estenderlo, inclusi approfondimenti da parte di chi lo sviluppa, consulta: Ricerca di contenuti con l'IA | Crea con l'IA di Google. In caso contrario, puoi iniziare a estendere il progetto seguendo le istruzioni riportate di seguito.

Panoramica

Il progetto Docs Agent fornisce un'interfaccia di ricerca conversazionale per un insieme di contenuti specifico, supportata dall'API Google Gemini e dai modelli generativi. Gli utenti possono fare una domanda dettagliata in uno stile di conversazione e ricevere una risposta dettagliata in base a un insieme specifico di contenuti. Dietro le quinte, l'agente Docs prende la domanda e esegue ricerche in un database vettoriale dei contenuti, creando un prompt dettagliato per il modello generativo, inclusi snippet di testo pertinente. Il modello generativo genera una risposta alla domanda e l'agente Docs la formatta e la presenta all'utente.

Figura 1. Diagramma funzionale dell'app del progetto Docs Agent.

La chiave per consentire all'agente di Documenti di rispondere a domande sui tuoi contenuti è la creazione di un database di vettori di questi contenuti. Dividi i contenuti in blocchi di testo logici e genera un vettore per ciascuno. Questi vettori sono rappresentazioni numeriche delle informazioni in ogni chunk e vengono generati con una funzione di incorporamento del testo basata sull'IA dei modelli generativi di Google.

Quando un utente pone una domanda, l'agente Docs utilizza la stessa funzione di embedding del testo per creare una rappresentazione numerica della domanda e utilizza questo valore per cercare nel database di vettori e trovare contenuti correlati. Prende i risultati migliori e aggiunge queste informazioni a un prompt per il modello generativo. Il modello di IA prende la domanda e le informazioni aggiuntive sul contesto e genera una risposta.

Configurazione del progetto

Queste istruzioni illustrano la procedura per configurare il progetto Docs Agent per lo sviluppo e i test. I passaggi generali sono l'installazione di alcuni software di prerequisiti, l'impostazione di alcune variabili di ambiente, la clonazione del progetto dal repository del codice e l'esecuzione dell'installazione della configurazione. Il progetto di codice utilizza Python Poetry per gestire i pacchetti e l'ambiente di runtime Python.

Installa i prerequisiti

Il progetto Docs Agent utilizza Python 3 e Python Poetry per gestire i pacchetti e eseguire l'applicazione. Le seguenti istruzioni di installazione si riferiscono a una macchina host Linux.

Per installare il software necessario:

1. Installa Python 3 e il pacchetto dell'ambiente virtuale venv per Python.
   

   sudo apt update
   sudo apt install git pip python3-venv
   

2. Installa Python Poetry per gestire le dipendenze e il packaging per il progetto.
   

   curl -sSL https://install.python-poetry.org | python3 -
   

Puoi utilizzare Python Poetry per aggiungere altre librerie Python se estendi il progetto.

Imposta le variabili di ambiente

Imposta alcune variabili di ambiente necessarie per consentire l'esecuzione del progetto di codice di Docs Agent, inclusa una chiave API Google Gemini e un'impostazione di Python Poetry. Se utilizzi Linux, ti consigliamo di aggiungere queste variabili al file $HOME/.bashrc per impostarle come predefinite per le sessioni del terminale.

Per impostare le variabili di ambiente:

1. Ottieni una chiave API Google Gemini e copia la stringa della chiave.
2. Imposta la chiave API come variabile di ambiente. Sugli host Linux, utilizza il seguente comando.
   

   export API_KEY=<YOUR_API_KEY_HERE>
   

3. Risolvi un problema noto per Python Poetry impostando il parametro PYTHON_KEYRING_BACKEND. Sugli host Linux, utilizza il seguente comando.
   

   export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring
   

Clona e configura il progetto

Scarica il codice del progetto e utilizza il comando di installazione di Poetry per scaricare le dipendenze richieste e configurare il progetto. Per recuperare il codice sorgente del progetto, hai bisogno del software di controllo del codice sorgente git. esterno Per scaricare e configurare il codice del progetto:

1. Clona il repository Git utilizzando il seguente comando.
   

   git clone https://github.com/google/generative-ai-docs
   

2. Facoltativamente, configura il tuo repository Git locale in modo da utilizzare il controllo sparse, in modo da avere solo i file per il progetto Docs Agent.
   

   cd generative-ai-docs/
   git sparse-checkout init --cone
   git sparse-checkout set examples/gemini/python/docs-agent/
   

3. Vai alla directory principale del progetto docs-agent.
   

   cd examples/gemini/python/docs-agent/
   

4. Esegui il comando di installazione di Poetry per scaricare le dipendenze e configurare il progetto:
   

   poetry install
   

Preparare i contenuti

Il progetto Docs Agent è progettato per funzionare con contenuti di testo e include strumenti specifici per lavorare con siti web che utilizzano Markdown come formato di origine. Se utilizzi i contenuti di un sito web, devi conservare (o replicare) la struttura di directory del sito web pubblicato per consentire all'attività di elaborazione dei contenuti di mappare e creare link a questi contenuti.

A seconda del formato e dei dettagli dei contenuti, potresti doverli pulire per rimuovere informazioni non pubbliche, note interne o altre informazioni che non vuoi che siano disponibili per la ricerca. Devi mantenere la formattazione di base, come titoli e intestazioni, che consentono di creare suddivisioni logiche del testo, o chunk, nel passaggio di elaborazione dei contenuti.

Per preparare i contenuti all'elaborazione:

1. Crea una directory per i contenuti che vuoi che l'agente IA cerchi.
   

   mkdir docs-agent/content/
   

2. Copia i contenuti nella directory docs-agent/content/. Se i contenuti sono un sito web, conserva (o replica) la struttura di directory del sito web pubblicato.
3. Pulisci o modifica i contenuti in base alle esigenze per rimuovere informazioni non pubbliche o altre informazioni che non vuoi includere nelle ricerche.

Utilizzare la documentazione di Flutter per i test

Se hai bisogno di un insieme di contenuti per testare Docs Agent, puoi utilizzare la documentazione per gli sviluppatori Flutter per i test.

Per scaricare la documentazione per gli sviluppatori Flutter:

1. Vai alla directory dei contenuti che vuoi che l'agente IA esamini.

   cd docs-agent/content/
   

2. Clona la documentazione di Flutter nella directory docs-agent/content/.
   

   git clone --recurse-submodules https://github.com/flutter/website.git
   

Elaborare i contenuti

Affinché l'agente di ricerca possa cercare efficacemente contenuti correlati alle domande degli utenti, devi creare un database di vettori che rappresentino i tuoi contenuti. I vettori vengono generati utilizzando una funzione del modello di IA generativa chiamata embedding del testo. Gli incorporamenti di testo sono rappresentazioni numeriche dei contenuti del testo. Approssimano il significato semantico del testo come insieme di numeri. Avere rappresentazioni numeriche delle informazioni consente al sistema di prendere la domanda di un utente, approssimarne il significato utilizzando la stessa funzione di embedding del testo e poi trovare le informazioni correlate come calcolo matematico, utilizzando un algoritmo K-Nearest Neighbor (K-NN).

Suddividere i contenuti di testo

La quantità di testo che un vettore di incorporamento del testo può rappresentare in modo efficace è limitata. Questo progetto limita il testo rappresentato in un vettore a 3000 caratteri o meno, il che significa che devi suddividere i contenuti in blocchi che non superano questo limite di caratteri. Questa sezione descrive come utilizzare uno script fornito con il progetto Docs Agent per suddividere i file Markdown in blocchi di testo più piccoli. Per suggerimenti su come lavorare con altri formati di contenuti, consulta Gestire altri formati.

Per suddividere i contenuti in formato Markdown:

1. Configura i parametri di input per lo script di elaborazione modificando il file docs-agent/config.yaml. Questo esempio ha come target un sottoinsieme della documentazione di Flutter:
   

   input:
   - path: "content/website/src/ui"
     url_prefix: "https://docs.flutter.dev/ui"

2. Salva le modifiche a questo file di configurazione.
3. Vai alla directory del progetto docs-agent:
   

   cd docs-agent/
   

4. Dividi i contenuti della sorgente Markdown eseguendo il comando agent chunk:
   

   agent chunk
   

Lo script elabora i contenuti in input e crea file di testo di output nella directory docs-agent/data, dividendo il testo in base a titoli, intestazioni e paragrafi correlati. L'elaborazione potrebbe richiedere del tempo, a seconda delle dimensioni dei contenuti.

Crea vettori di incorporamento del testo

Dopo aver suddiviso i contenuti in blocchi di dimensioni appropriate e significativi, puoi compilare il database di vettori con i tuoi contenuti utilizzando una funzione di incorporamento del testo. Il progetto Docs Agent utilizza il database di vettori Chroma per memorizzare i vettori di embedding del testo. Queste istruzioni spiegano come utilizzare lo script Docs Agents per compilare un database di vettori con i contenuti suddivisi.

Per generare incorporamenti di testo e compilare il database di vettori:

1. Vai alla directory del progetto docs-agent:
   

   cd docs-agent/
   

2. Compila il database di vettori con i tuoi contenuti utilizzando il agent populate comando:
   

   agent populate
   

Questo script utilizza l'API Google Gemini per generare vettori di incorporamento del testo e poi salva l'output nel database dei vettori. L'elaborazione potrebbe richiedere del tempo, a seconda delle dimensioni dei contenuti.

Gestire altri formati

Il progetto Docs Agent è progettato per funzionare con i contenuti dei siti web in formato Markdown. Gli autori del progetto hanno creato alcuni script di conversione per generare altri tipi di contenuti in formato Markdown, tra cui Documenti Google, Formato Documento Portatile (PDF) e Gmail. Per ulteriori informazioni sull'utilizzo di questi convertori, consulta la directory docs-agent/apps_script del repository del codice.

Convertire altri formati di contenuti

Puoi utilizzare altri formati di contenuti con il progetto, ma questi metodi aggiuntivi devono essere creati da te o da altri membri della community. Controlla il repository di codice Issues e Pull Request per trovare persone che sviluppano soluzioni simili.

Il codice chiave da creare per supportare altri formati di contenuti è uno script di suddivisione come lo script files_to_plain_text.py. Cerca di creare uno script o un programma che generi un output simile a questo script. Ricorda che l'output di testo finale deve avere una formattazione minima e informazioni estranee. Se utilizzi formati di contenuti come HTML o JSON, assicurati di rimuovere il maggior numero possibile di formattazioni non informative (tag, scripting, CSS) in modo che non alterino i valori degli embedding di testo che generi.

Dopo aver creato uno script di separazione per il formato dei contenuti, dovresti essere in grado di eseguire lo script populate_vector_database.py per compilare il database di vettori. Per ulteriori informazioni sull'elaborazione di file da utilizzare con Docs Agent, consulta la preelaborazione Readme di Docs Agent.

Testa l'app

Una volta completato il popolamento del database di vettori, il progetto è pronto per i test. Il progetto fornisce una funzione di imballaggio per consentirti di eseguire il progetto localmente.

Per eseguire e testare l'interfaccia web del progetto:

1. Vai alla directory del progetto docs-agent:
   

   cd docs-agent/
   

2. Esegui lo script di avvio dell'applicazione web:
   

   agent chatbot
   

3. Utilizzando il browser web, vai all'indirizzo web dell'URL mostrato nell'output dello script di avvio e testa l'applicazione.
   

   * Running on http://your-hostname-here:5000
   

Opzioni di implementazione

L'API Gemini fornisce strumenti di programmazione che possono sostituire i componenti dell'implementazione di Docs Agent, in particolare: la ricerca semantica e la variante del modello Gemini per le risposte alle domande con attributi (AQA). Puoi utilizzare la funzionalità di ricerca semantica dell'API Gemini per sostituire il database di vettori separato. La funzionalità di recupero semantico consente di generare incorporamenti per i contenuti e di archiviarli. Il modello Gemini di AQA è ottimizzato per rispondere alle domande con il materiale di origine fornito in un prompt. Puoi utilizzare il recupero semantico insieme al modello AQA per rispondere a domande sui tuoi contenuti all'interno dell'API Gemini.

Docs Agent include opzioni di configurazione per utilizzare la funzionalità dell'API Semantic Retrieval o il modello AQA Gemini oppure entrambe. Per ulteriori informazioni, consulta la guida di Docs Agent.

Risorse aggiuntive

Per ulteriori informazioni sul progetto Docs Agent, consulta il repository del codice. Se hai bisogno di aiuto per creare l'applicazione o stai cercando sviluppatori collaborati, dai un'occhiata al server di Discord della community degli sviluppatori Google.

Applicazioni di produzione

Se prevedi di implementare Docs Agent per un pubblico ampio, tieni presente che l'utilizzo dell'API Google Gemini potrebbe essere soggetto a limitazioni di frequenza e altre limitazioni di utilizzo. Se stai pensando di creare un'applicazione di produzione con l'API Gemini come Docs Agent, dai un'occhiata ai servizi Vertex AI di Google Cloud per aumentare la scalabilità e l'affidabilità della tua app.