Gemini 2.0 Flash sperimentale è ora disponibile. Scopri di più

Questa pagina è stata tradotta dall'API Cloud Translation.

Esplora le funzionalità di elaborazione dei documenti con l'API Gemini

L'API Gemini supporta l'input PDF, inclusi i documenti lunghi (fino a 3600 pagine). I modelli Gemini elaborano i PDF con la visione nativa e sono quindi in grado di comprendere sia i contenuti di testo che quelli delle immagini all'interno dei documenti. Con il supporto della visione di PDF nativa, i modelli Gemini sono in grado di:

Analizza diagrammi, grafici e tabelle all'interno dei documenti.
Estrai le informazioni in formati di output strutturati.
Rispondere a domande sui contenuti visivi e di testo nei documenti.
Riassumere i documenti.
Trascrivere i contenuti dei documenti (ad es.in HTML) preservando i layout e la formattazione, per l'utilizzo in applicazioni a valle (ad es. nelle pipeline RAG).

Questo tutorial mostra alcuni possibili modi per utilizzare l'API Gemini con i documenti PDF. Tutto l'output è solo di testo.

Prima di iniziare: configura il progetto e la chiave API

Prima di chiamare l'API Gemini, devi configurare il progetto e la chiave API.

Espandi per scoprire come configurare il progetto e la chiave API

Ottieni e proteggi la tua chiave API

Per chiamare l'API Gemini, devi disporre di una chiave API. Se non ne hai già una, crea una chiave in Google AI Studio.

Ottieni una chiave API

Ti consigliamo vivamente di non inserire una chiave API nel tuo sistema di controllo della versione.

Devi archiviare la chiave API in un archivio di secret come Secret Manager di Google Cloud.

Questo tutorial presuppone che tu stia accedendo alla chiave API come variabile di ambiente.

Installa il pacchetto SDK e configura la chiave API

L'SDK Python per l'API Gemini è contenuto nel pacchetto google-generativeai.

Installa la dipendenza utilizzando pip:
```
pip install -U google-generativeai
```

Importa il pacchetto e configura il servizio con la tua chiave API:

import os
import google.generativeai as genai

genai.configure(api_key=os.environ['API_KEY'])

Prompt con i PDF

Questa guida mostra come caricare ed elaborare i PDF utilizzando l'API File o includendoli come dati in linea.

Dettagli tecnici

Gemini 1.5 Pro e 1.5 Flash supportano un massimo di 3600 pagine di documento. Le pagine del documento devono essere in uno dei seguenti tipi MIME di dati di testo:

PDF - application/pdf
JavaScript - application/x-javascript, text/javascript
Python - application/x-python, text/x-python
TXT - text/plain
HTML - text/html
CSS - text/css
Markdown - text/md
CSV - text/csv
XML - text/xml
RTF - text/rtf

Ogni pagina del documento equivale a 258 token.

Sebbene non esistano limiti specifici al numero di pixel in un documento oltre alla finestra di contesto del modello, le pagine più grandi vengono ridimensionate a una risoluzione massima di 3072 x 3072 mantenendo le proporzioni originali, mentre le pagine più piccole vengono ridimensionate a 768 x 768 pixel. Non è prevista alcuna riduzione dei costi per le pagine di dimensioni inferiori, ad eccezione della larghezza di banda, né un miglioramento delle prestazioni per le pagine di risoluzione superiore.

Per ottenere risultati ottimali:

Ruota le pagine nell'orientamento corretto prima del caricamento.
Evita pagine sfocate.
Se utilizzi una singola pagina, posiziona il prompt di testo dopo la pagina.

Input PDF

Per i payload PDF di dimensioni inferiori a 20 MB, puoi scegliere tra caricare documenti codificati in base64 o caricare direttamente i file archiviati localmente.

Documenti con codifica Base64

Puoi elaborare i documenti PDF direttamente dagli URL. Ecco uno snippet di codice che mostra come:

import httpx
import base64

model = genai.GenerativeModel("gemini-1.5-flash")
doc_url = "https://discovery.ucl.ac.uk/id/eprint/10089234/1/343019_3_art_0_py4t4l_convrt.pdf"  # Replace with the actual URL of your PDF

# Retrieve and encode the PDF
doc_data = base64.standard_b64encode(httpx.get(doc_url).content).decode("utf-8")

prompt = "Summarize this document"

response = model.generate_content([{'mime_type':'application/pdf', 'data': doc_data}, prompt])
print(response.text)

PDF archiviati localmente

Per i PDF archiviati localmente, puoi utilizzare il seguente approccio:

import base64

model = genai.GenerativeModel("gemini-1.5-flash")
doc_path = "/path/to/file.pdf" # Replace with the actual path to your local PDF

# Read and encode the local file
with open(doc_path, "rb") as doc_file:
    doc_data = base64.standard_b64encode(doc_file.read()).decode("utf-8")

prompt = "Summarize this document"

response = model.generate_content([{'mime_type': 'application/pdf', 'data': doc_data}, prompt])

print(response.text)

PDF di grandi dimensioni

Puoi utilizzare l'API File per caricare un documento di qualsiasi dimensione. Utilizza sempre l'API File quando le dimensioni totali della richiesta (inclusi i file, il prompt di testo, le istruzioni di sistema e così via) sono superiori a 20 MB.

Chiama media.upload per caricare un file utilizzando l'API File. Il seguente codice carica un file di documento e lo utilizza in una chiamata a models.generateContent.

PDF di grandi dimensioni da URL (:#large-pdfs-urls)

Utilizza l'API File per i file PDF di grandi dimensioni disponibili tramite URL, semplificando il processo di caricamento ed elaborazione di questi documenti direttamente tramite i relativi URL:

import io
import httpx

model = genai.GenerativeModel("gemini-1.5-flash")
long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf" # Replace with the actual URL of your large PDF

# Retrieve and upload the PDF using the File API
doc_data = io.BytesIO(httpx.get(long_context_pdf_path).content)
sample_doc = genai.upload_file(data=doc_data, mime_type='application/pdf')

prompt = "Summarize this document"

response = model.generate_content([sample_doc, prompt])
print(response.text)

PDF di grandi dimensioni archiviati localmente (:#large-pdfs-local)

import google.generativeai as genai

model = genai.GenerativeModel("gemini-1.5-flash")
sample_pdf = genai.upload_file(media / "test.pdf")
response = model.generate_content(["Give me a summary of this pdf file.", sample_pdf])
print(response.text)files.py

Puoi verificare che l'API abbia archiviato correttamente il file caricato e recuperarne i metadati chiamando files.get. Solo name (e per estensione uri) sono univoci.

import google.generativeai as genai

myfile = genai.upload_file(media / "poem.txt")
file_name = myfile.name
print(file_name)  # "files/*"

myfile = genai.get_file(file_name)
print(myfile)files.py

Più PDF

L'API Gemini è in grado di elaborare più documenti PDF in una singola richiesta, purché le dimensioni combinate dei documenti e del prompt di testo rimangano all'interno della finestra di contesto del modello.

import io
import httpx

model = genai.GenerativeModel("gemini-1.5-flash")

doc_url_1 = "https://arxiv.org/pdf/2312.11805" # Replace with the URL to your first PDF
doc_url_2 = "https://arxiv.org/pdf/2403.05530" # Replace with the URL to your second PDF

# Retrieve and upload both PDFs using the File API
doc_data_1 = io.BytesIO(httpx.get(doc_url_1).content)
doc_data_2 = io.BytesIO(httpx.get(doc_url_2).content)

sample_pdf_1 = genai.upload_file(data=doc_data_1, mime_type='application/pdf')
sample_pdf_2 = genai.upload_file(data=doc_data_2, mime_type='application/pdf')

prompt = "What is the difference between each of the main benchmarks between these two papers? Output these in a table."

response = model.generate_content([sample_pdf_1, sample_pdf_2, prompt])
print(response.text)

Elenco file

Puoi elencare tutti i file caricati utilizzando l'API File e i relativi URI utilizzando files.list.

import google.generativeai as genai

print("My files:")
for f in genai.list_files():
    print("  ", f.name)files.py

Elimina file

I file caricati utilizzando l'API File vengono eliminati automaticamente dopo 2 giorni. Puoi anche eliminarli manualmente utilizzando files.delete.

import google.generativeai as genai

myfile = genai.upload_file(media / "poem.txt")

myfile.delete()

try:
    # Error.
    model = genai.GenerativeModel("gemini-1.5-flash")
    result = model.generate_content([myfile, "Describe this file."])
except google.api_core.exceptions.PermissionDenied:
    passfiles.py

Memorizzazione nella cache del contesto con i PDF

import os
from google.generativeai import caching
import io
import httpx

# Define the path to the PDF document (or use a URL)
long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf" # Replace with the URL of your large PDF
doc_data = io.BytesIO(httpx.get(long_context_pdf_path).content)

# Upload the PDF document using the File API
document = genai.upload_file(data=doc_data, mime_type='application/pdf')

# Specify the model name and system instruction for caching
model_name = "gemini-1.5-flash-002" # Ensure this matches the model you intend to use
system_instruction = "You are an expert analyzing transcripts."

# Create a cached content object
cache = caching.CachedContent.create(
    model=model_name,
    system_instruction=system_instruction,
    contents=[document], # The document(s) and other content you wish to cache
)

# Display the cache details
print(cache)

# Initialize a generative model from the cached content
model = genai.GenerativeModel.from_cached_content(cache)

# Generate content using the cached prompt and document
response = model.generate_content("Please summarize this transcript")

# (Optional) Print usage metadata for insights into the API call
print(response.usage_metadata)

# Print the generated text
print(response.text)

Elenca le cache

Non è possibile recuperare o visualizzare i contenuti memorizzati nella cache, ma puoi recuperare i metadati della cache (name, model, display_name, usage_metadata, create_time, update_time e expire_time).

Per elencare i metadati di tutte le cache caricate, utilizza CachedContent.list():

for c in caching.CachedContent.list():
  print(c)

Aggiornare una cache

Puoi impostare un nuovo ttl o expire_time per una cache. La modifica di qualsiasi altro elemento della cache non è supportata.

L'esempio seguente mostra come aggiornare il ttl di una cache utilizzando CachedContent.update().

import datetime

cache.update(ttl=datetime.timedelta(hours=2))

Eliminare una cache

Il servizio di memorizzazione nella cache fornisce un'operazione di eliminazione per rimuovere manualmente i contenuti dalla cache. L'esempio seguente mostra come eliminare una cache utilizzando CachedContent.delete().

cache.delete()

Passaggi successivi

Questa guida mostra come utilizzare generateContent e generare output di testo dai documenti elaborati. Per saperne di più, consulta le seguenti risorse:

Strategie di prompt dei file: l'API Gemini supporta i prompt con dati di testo, immagini, audio e video, noti anche come prompt multimodali.
Istruzioni di sistema: le istruzioni di sistema ti consentono di indirizzare il comportamento del modello in base alle tue esigenze e ai tuoi casi d'uso specifici.
Indicazioni per la sicurezza: a volte i modelli di IA generativa producono output inaspettati, ad esempio imprecisi, biassati o offensivi. Il post-trattamento e la valutazione umana sono essenziali per limitare il rischio di danni derivanti da questi output.