Utilizzo del supporto PDF e allegati con i bot AI

[sam (Sam Saffron)]

Questa guida spiega come abilitare e utilizzare il supporto nativo per PDF e allegati di documenti quando si interagisce con i bot di intelligenza artificiale (AI) in Discourse. Gli utenti possono caricare PDF e altri documenti direttamente nelle conversazioni con gli agenti AI.

Livello utente richiesto: Amministratore

Riepilogo

Discourse AI ora supporta la gestione nativa degli allegati, consentendo agli utenti di caricare PDF e altri tipi di documenti direttamente durante la conversazione con i bot AI. L’AI può leggere e comprendere il contenuto di questi allegati, abilitando casi d’uso come l’analisi di documenti, la sintesi e la risposta a domande basate sui file caricati.

Questa funzionalità richiede:

• Tipi di allegati consentiti configurati sull’LLM (Modello Linguistico di Grande Scala)
• Un agente con la visione abilitata (questo controlla se i caricamenti sono inclusi nei messaggi)
• L’estensione del file deve essere autorizzata nelle impostazioni di caricamento del tuo sito

Provider supportati

Il supporto nativo per gli allegati funziona con i modelli dei seguenti provider:

• Anthropic (modelli Claude)
• AWS Bedrock (modelli Claude tramite Bedrock)
• Google (modelli Gemini)
• OpenAI (modelli GPT)
• Azure (modelli compatibili con OpenAI)
• OpenRouter (modelli compatibili con OpenAI)

Ogni provider gestisce gli allegati in modo diverso a livello di API, ma Discourse AI lo gestisce automaticamente. Tieni presente che diversi provider implementano diversi livelli di supporto per i vari tipi di allegati.

Tipi di allegati supportati

I seguenti tipi di documenti possono essere configurati per l’elaborazione AI:

Tipo	Estensioni
PDF	pdf
Testo semplice	txt
Microsoft Word	doc, docx
Rich Text Format	rtf
HTML	html, htm
Markdown	md, markdown

Le immagini sono gestite separatamente tramite l’impostazione “Vision enabled” e non richiedono la configurazione del tipo di allegato.

Configurazione

Passaggio 1: Autorizzare le estensioni dei file per il caricamento

Prima che gli utenti possano caricare allegati, assicurati che le estensioni dei file siano autorizzate nelle impostazioni del tuo sito.

1. Naviga su Amministrazione → File
2. Trova l’impostazione authorized extensions (estensioni autorizzate)
3. Aggiungi le estensioni che desideri consentire (ad esempio, pdf|txt|docx)

Passaggio 2: Configurare il modello LLM

1. Naviga su Amministrazione → Plugin → Discourse AI → LLMs
2. Seleziona il modello LLM che desideri configurare (o creane uno nuovo)
3. Nel campo Allowed attachments (Allegati consentiti), seleziona o digita le estensioni di file che desideri che il modello accetti (ad esempio, pdf, txt, docx)

Se lasci vuoto il campo “Allowed attachments”, gli allegati di documenti verranno disabilitati per quel modello. Le immagini sono controllate separatamente tramite l’interruttore “Vision enabled”.

Passaggio 3: Configurare l’agente

1. Naviga su Amministrazione → Plugin → Discourse AI → Agents
2. Seleziona o crea un agente
3. Assicurati che Vision enabled (Visione abilitata) sia attivo: questo controlla se i caricamenti (sia immagini che documenti) sono inclusi nei messaggi inviati all’LLM
4. Imposta Default model (Modello predefinito) su un LLM che ha allegati configurati

Come funziona

Quando un utente carica un documento in una conversazione con un bot AI:

1. Il documento viene caricato su Discourse utilizzando la gestione standard dei caricamenti
2. Discourse AI codifica il contenuto del documento (base64)
3. Il contenuto codificato viene inviato all’LLM insieme al messaggio dell’utente
4. L’LLM elabora sia il messaggio di testo sia il contenuto del documento
5. L’AI risponde in base al contesto combinato

Dettagli tecnici

• I documenti vengono codificati in base64 e inviati inline con la richiesta
• Ogni provider riceve gli allegati nel suo formato nativo:
  • Anthropic: Utilizza il tipo document con sorgente base64
  • Gemini: Utilizza il formato inlineData
  • OpenAI (API Chat Completions): Utilizza il tipo file con file_data contenente il contenuto base64
  • OpenAI (API Risposte): Utilizza il tipo input_file con file_data contenente il contenuto base64
• I limiti di dimensione dei file sono regolati dall’impostazione del tuo sito max attachment size kb (dimensione massima allegato in kb)

Casi d’uso

Il supporto nativo per gli allegati abilita diversi flussi di lavoro:

• Analisi di documenti: Carica contratti, report o documenti di ricerca affinché l’AI li sintetizzi o risponda a domande su di essi
• Revisione di contenuti: Fai in modo che l’AI esamini e fornisca feedback sui documenti in bozza
• Estrazione dati: Estrai informazioni specifiche da documenti caricati
• Assistenza alla traduzione: Carica documenti in una lingua e discuti il contenuto o richiedi traduzioni
• Supporto tecnico: Gli utenti possono caricare file di log o file di configurazione per assistenza nella risoluzione dei problemi

Limitazioni

• Dimensione del file: Gli allegati sono limitati dalle impostazioni di dimensione di caricamento del tuo sito e dal fornitore LLM
• Supporto del provider: Il supporto per gli allegati richiede un dialetto del provider che gestisca i documenti (Anthropic, AWS Bedrock, Google, OpenAI, Azure e OpenRouter)
• Requisito di visione dell’agente: L’agente deve avere l’opzione “Vision enabled” attivata affinché i caricamenti vengano inclusi nei messaggi
• Corrispondenza dell’estensione: L’estensione del file deve essere sia autorizzata per il caricamento sul tuo sito sia consentita nella configurazione dei tipi di allegati dell’LLM
• I risultati variano: Poiché i fornitori LLM e gli LLM elaborano i file, il costo/accuratezza e i risultati varieranno. Anthropic tende a utilizzare più token per l’analisi rispetto a OpenAI o Google.
• Abilita la cache: Per OpenAI, assicurati di utilizzare l’API delle risposte che offre un supporto più coerente per la cache (quando il ragionamento è abilitato); per i modelli Anthropic, potrebbe essere necessario abilitare esplicitamente la cache nella configurazione LLM. Questo può essere particolarmente importante quando si hanno conversazioni a più turni.

Risoluzione dei problemi

Gli allegati non vengono elaborati

1. Verifica che l’estensione del file sia inclusa nell’impostazione authorized extensions del tuo sito
2. Conferma che il tipo di file sia elencato nell’impostazione “Allowed attachments” dell’LLM
3. Assicurati che l’agente abbia “Vision enabled” attivo e utilizzi un LLM configurato correttamente

Il caricamento fallisce

• Controlla l’impostazione max attachment size kb
• Verifica che l’estensione del file sia autorizzata
• I PDF molto grandi potrebbero non essere supportati; ogni fornitore LLM ha diverse dimensioni massime di caricamento.

L’AI non comprende il documento

• Assicurati di utilizzare un modello che supporti la comprensione dei documenti
• Prova un modello più capace (ad esempio, Claude Sonnet 4.5, GPT-5.1, Gemini Pro 3)

FAQ

Gli utenti possono caricare più documenti in un unico messaggio?
Sì, gli utenti possono includere più allegati in un singolo messaggio e l’AI avrà accesso a tutti.

Funziona sia in chat che nei messaggi privati (PM)?
Sì, il supporto per gli allegati funziona sia nei messaggi privati con i bot AI sia nei messaggi diretti in chat, a condizione che l’agente sia configurato per quei metodi di interazione.

È diverso dai caricamenti RAG sugli agenti?
Sì. I caricamenti RAG sono documenti aggiunti dagli amministratori alla base di conoscenza di un agente, che vengono indicizzati e ricercati. Il supporto nativo per gli allegati consente agli utenti finali di caricare documenti durante le conversazioni per un’analisi immediata senza indicizzazione.

Cosa succede ai documenti caricati?
I documenti vengono elaborati in base alle norme standard di gestione dei caricamenti e di conservazione del tuo sito. Vengono archiviati come normali caricamenti di Discourse.

Risorse aggiuntive

• Discourse AI
• AI bot - Agents
• PDF support in Discourse AI (RAG)
• Discourse AI - AI bot