Skip to main content

​
Panoramica

Le connessioni LLM in ABBYY Vantage consentono di integrare potenti modelli linguistici di fornitori come OpenAI e Microsoft Foundry direttamente nei tuoi flussi di lavoro di elaborazione documentale. Queste connessioni permettono alle tue Document skill di sfruttare l’intelligenza artificiale più avanzata per migliorare l’estrazione, la classificazione e la comprensione di documenti complessi. Cosa potrai fare:
  • Accedere alla configurazione di Connections
  • Aggiungere una nuova connessione LLM
  • Configurare le credenziali e le impostazioni della connessione
  • Verificare la connessione
Tempo necessario: 10-15 minuti Provider LLM supportati:
  • OpenAI ChatGPT
  • Microsoft Foundry
Nota: Attualmente le connessioni LLM possono essere utilizzate nelle Document skill solo tramite ABBYY Advanced Designer.

​
Prerequisiti

Prima di iniziare, assicurati di avere:
  1. Accesso come amministratore alla configurazione di ABBYY Vantage.
  2. Credenziali API dal fornitore LLM scelto:
    • OpenAI: chiave API dal tuo account OpenAI
    • Microsoft Foundry: chiave API, URL completo dell’endpoint (incluso il percorso /chat/completions e la versione dell’API) e nome del modello da Microsoft Foundry in Azure.
  3. Abbonamento attivo con il tuo fornitore LLM.
Nota: Le connessioni LLM sono gestite a livello di tenant e possono essere utilizzate da tutti i designer di Skill della tua organizzazione. Attualmente, le connessioni LLM possono essere integrate nelle Document skill solo tramite ABBYY Advanced Designer.

​
Passaggio 1: Accedere alle impostazioni di configurazione

Vai all’area Configuration, dove gestirai le connessioni LLM.
  1. Nell’interfaccia di ABBYY Vantage, individua la sezione ADMIN nella barra laterale sinistra.
  2. Fai clic su Configuration (icona a forma di ingranaggio).
Accessing Configuration Vedrai la pagina Configuration con diverse opzioni nel menu a sinistra:
  • General
  • Connections (qui è dove lavoreremo)
  • Identity Provider
  • Public API Client
  • Security Log
  • Environment Variables
  • IP Restrictions

​
Step 2: Vai a Connections

Accedi all’interfaccia di gestione di Connections.
  1. Nel menu di sinistra Configuration, fai clic su Connections.
Pagina Connections La pagina Connections visualizza:
  • L’elenco delle connessioni esistenti (se presenti)
  • I dettagli della connessione: Name, Description, Used in Skills, Last Updated
  • I pulsanti di gestione: Add Connection, Test, Edit, Delete
  • La funzionalità di ricerca per trovare connessioni specifiche
Nota: Le Connections sono risorse condivise. Tutti i progettisti di skill nel tuo tenant possono usare queste connessioni nelle loro skill.

​
Passaggio 3: Aggiungere una nuova connessione LLM

Avviare il processo di creazione di una nuova connessione al provider LLM.
  1. Fare clic sul pulsante + Add Connection nella parte superiore della pagina Connections.
  2. Viene visualizzata la finestra di dialogo Add Connection, che mostra i provider LLM disponibili:
    • OpenAI ChatGPT - Connessione diretta all’API di OpenAI
    • Microsoft Foundry - Modelli OpenAI e altri modelli di intelligenza artificiale ospitati sull’infrastruttura Azure di Microsoft
  3. Selezionare il provider desiderato (in questo esempio, verrà utilizzato Microsoft Foundry).
  4. Fare clic su Next.
Nota: ciascun provider ha requisiti di configurazione diversi. Scegliere il provider che corrisponde all’abbonamento LLM della propria organizzazione.

​
Passaggio 4: Configurare i dettagli della connessione

Compila le informazioni richieste per la connessione al LLM. Connection Configuration

​
Impostazioni generali

Name
  • Un identificatore univoco per questa connessione
  • Esempio: Microsoft Foundry oppure Production GPT-4
  • Questo nome verrà visualizzato quando si selezionano le connessioni nelle Document Skill.
Description
  • Facoltativa ma consigliata.
  • Fornisci informazioni utili sulla connessione.
  • Esempio: “Microsoft Foundry Connection 1” oppure “GPT-4 Production API”.
  • Importante: non includere credenziali sensibili nella descrizione.
Nota: scegli nomi descrittivi che aiutino gli Skill Designer a capire quale connessione utilizzare per i vari scopi.

​
Impostazioni di connessione

I field obbligatori dipendono dal provider LLM che utilizzi:

​
Per Microsoft Foundry:

Api Key
  • La tua chiave API di Microsoft Foundry dal portale Azure.
  • Puoi trovarla in: Azure Portal → Your Microsoft Foundry Resource → Keys and Endpoint.
  • Formato: una lunga stringa alfanumerica.
  • Segnaposto di esempio: [API Key Here]
Url
  • L’URL dell’endpoint di Microsoft Foundry.
  • Puoi trovarlo in: Azure Portal → Your Microsoft Foundry Resource → Keys and Endpoint.
  • Formato: https://[resource].cognitiveservices.azure.com/openai/deployments/[model-name]/chat/completions?api-version=2025-01-01-preview
  • Esempio: https://[redacted]resource.cognitiveservices.azure.com/openai/deployments/gpt-4.1-nano/chat/completions?api-version=2025-01-01-preview
Model Name
  • Il nome del modello distribuito in Microsoft Foundry.
  • Puoi trovarlo in: Azure Portal → Your Microsoft Foundry Resource → Deployments.
  • Esempio: gpt-4.1-nano, gpt-35-turbo, gpt-4
  • Questo deve corrispondere esattamente alla tua distribuzione.

​
Per OpenAI ChatGPT:

API Key
  • La tua chiave API OpenAI da platform.openai.com.
  • Puoi trovarla in: OpenAI Platform → API Keys.
  • Formato: inizia con sk-
Model
  • Il modello specifico da utilizzare (ad esempio, gpt-4, gpt-3.5-turbo)
Avvertenza: Non condividere mai le chiavi API e non includerle nelle descrizioni. Queste credenziali consentono l’accesso ai tuoi servizi LLM e possono generare costi.

​
Passaggio 5: verifica la connessione

Verifica che la connessione sia configurata correttamente prima di salvarla.
  1. Dopo aver inserito tutte le informazioni richieste, fai clic sul pulsante Test.
Testing Connection
  1. Vantage tenterà di connettersi al tuo provider LLM utilizzando le credenziali che hai fornito.
  2. Controlla il risultato del test:
    • Successo (segno di spunta verde): la connessione funziona correttamente.
    • Errore (X rossa o messaggio di errore): controlla le credenziali e riprova.

​
Risultati del test

Test riuscito:
  • Appare un segno di spunta verde accanto alla connessione.
  • Ora puoi salvare la connessione.
  • La connessione è pronta per essere utilizzata nelle Document skill.
Test non riuscito:
  • Esamina il messaggio di errore per individuare i problemi specifici.
  • Problemi comuni:
    • API key non corretta
    • Endpoint URL non valido
    • Nome del modello errato
    • Problemi di connettività di rete
    • Autorizzazioni o quota insufficienti
Nota: Verifica sempre la connessione prima di salvarla. In questo modo le tue Document skill potranno utilizzare correttamente il provider LLM.

​
Passaggio 6: Salva la tua connessione

Completa la configurazione della connessione.
  1. Una volta che il test ha avuto esito positivo, fai clic su Add.
  2. La tua connessione ora compare nell’elenco Connections.
  3. La connessione è immediatamente disponibile per tutti i progettisti di skill nel tuo tenant.
La pagina Connections ora mostra:
  • Connection name: Come lo hai specificato
  • Description: La descrizione che hai fornito
  • Used in Skills: Indicherà quali skill utilizzano questa connessione
  • Last Updated: Data e ora correnti

​
Gestione delle connessioni esistenti

Puoi gestire le connessioni una volta create.

​
Modificare una connessione

  1. Selezionare la connessione dall’elenco.
  2. Fare clic sul pulsante Edit (icona a forma di matita).
  3. Aggiornare i campi necessari.
  4. Testare nuovamente la connessione.
  5. Fare clic su Save.
Attenzione: La modifica di una connessione influisce su tutte le skill che la utilizzano. Eseguire test accurati dopo aver apportato le modifiche.

​
Testare una connessione

  1. Selezionare la connessione dall’elenco.
  2. Fare clic sul pulsante Test (icona di aggiornamento).
  3. Verificare che la connessione sia ancora attiva.
  4. Questa operazione è utile per la risoluzione dei problemi o per la verifica delle credenziali.

​
Eliminare una connessione

  1. Seleziona la connessione dall’elenco.
  2. Fai clic sul pulsante Delete (icona del cestino).
  3. Conferma l’eliminazione.
Avvertenza: non è possibile eliminare una connessione attualmente utilizzata in skill attive. Rimuovi prima la connessione da tutte le skill.

​
Risoluzione dei problemi

​
Test della connessione non riuscito

Problema: Il test di connessione restituisce un errore. Soluzioni:
  • Chiave API non valida:
    • Verifica di aver copiato correttamente l’intera chiave.
    • Controlla la presenza di spazi o caratteri aggiuntivi.
    • Rigenera la chiave nel portale del tuo provider, se necessario.
  • URL dell’endpoint non valido:
    • Assicurati che l’URL sia completo e correttamente formattato.
    • Verifica che l’URL corrisponda alla tua risorsa Azure.
    • Controlla eventuali errori di battitura nel percorso del deployment.
  • Nome del modello errato:
    • Verifica che il deployment esista nel tuo portale Azure.
    • Controlla ortografia e maiuscole/minuscole (case-sensitive).
    • Verifica che il deployment sia attivo e disponibile.
  • Problemi di rete:
    • Controlla la tua connessione a Internet.
    • Verifica che le impostazioni del firewall consentano connessioni HTTPS in uscita.
    • Verifica che la tua istanza Vantage possa raggiungere il provider LLM.
  • Quota o autorizzazioni:
    • Verifica che la tua sottoscrizione sia attiva.
    • Controlla di non aver superato i limiti di frequenza delle richieste.
    • Assicurati che la tua chiave API abbia le autorizzazioni necessarie.

​
La connessione funziona nel test ma non nelle skill

Problema: Il test ha esito positivo ma le skill non riescono a usare la connessione. Soluzioni:
  • Aggiorna la pagina di Skill Designer.
  • Seleziona nuovamente la connessione nella configurazione della skill.
  • Controlla i log degli errori della skill per eventuali messaggi specifici.
  • Verifica che la skill sia pubblicata e non in modalità bozza.

​
Costi delle API più alti del previsto

Problema: Addebiti imprevisti dal tuo fornitore di LLM. Soluzioni:
  • Verifica quali skill stanno utilizzando la connessione.
  • Controlla il volume e la frequenza dell’elaborazione.
  • Valuta l’implementazione di limiti di frequenza (rate limiting).
  • Monitora l’utilizzo tramite la dashboard del tuo provider.
  • Usa modelli più economici per i test.

​
Best practice consigliate

​
Sicurezza

  • Non condividere mai le chiavi API in chiaro via email o chat.
  • Ruota regolarmente le credenziali (consigliato ogni 90 giorni).
  • Usa connessioni separate per sviluppo e produzione.
  • Monitora i log di accesso nel pannello di controllo del tuo provider LLM.
  • Applica il principio del minimo privilegio: concedi solo le autorizzazioni necessarie.
  • Archivia le credenziali di backup in modo sicuro per le emergenze.

​
Gestione delle connessioni

  • Usa nomi descrittivi che indichino lo scopo o l’ambiente.
    • Esempi validi: “Produzione GPT-4”, “Sviluppo Microsoft Foundry”
    • Evita: “Connessione 1”, “Test”
  • Documenta nelle descrizioni a cosa serve ogni connessione
    • Includi: Ambiente, caso d’uso, contatto del referente
    • Escludi: Credenziali, informazioni sensibili
  • Verifica regolarmente le connessioni per individuare i problemi in anticipo
    • Imposta un piano di revisione mensile.
    • Esegui un test dopo qualsiasi modifica alle credenziali.
  • Monitora l’utilizzo per capire quali connessioni sono attive
    • Controlla la colonna “Used in Skills”.
    • Archivia o elimina le connessioni non utilizzate.

​
Gestione dei costi

  • Scegli modelli appropriati per ogni caso d’uso.
    • Usa modelli più piccoli e veloci per attività semplici.
    • Usa modelli avanzati per attività di estrazione complesse.
  • Implementa il rate limiting se il tuo provider lo supporta.
    • Evita picchi di costo imprevisti.
    • Protegge da elaborazioni fuori controllo.
  • Monitora i modelli di utilizzo
    • Configura avvisi di fatturazione nel pannello di controllo del tuo provider.
    • Rivedi periodicamente costi e volumi di utilizzo mensili.
  • Ottimizza i prompt nelle tue Document Skills.
    • Prompt efficienti riducono l’utilizzo di token.
    • Esegui test e perfeziona per ottenere i migliori risultati al costo più basso.

​
Ottimizzazione del flusso di lavoro

  • Raggruppa i tipi di documento simili
  • Configura Document skill appropriate per il caso d’uso
  • Esegui test con documenti di esempio prima dell’uso in produzione
  • Documenta il flusso di lavoro come riferimento per il team

​
Informazioni sui tipi di connessione

​
OpenAI ChatGPT

Ideale per:
  • Accesso diretto ai modelli OpenAI più recenti
  • Configurazione semplice usando solo una chiave API
  • Organizzazioni che già utilizzano la piattaforma OpenAI
Considerazioni:
  • I dati vengono elaborati dall’infrastruttura di OpenAI
  • È soggetto ai termini e alle norme sui dati di OpenAI
  • Richiede un account OpenAI e l’accesso all’API

​
Microsoft Foundry

Ideale per:
  • Implementazioni enterprise con infrastruttura Azure
  • Organizzazioni che richiedono controlli sulla residenza dei dati
  • Integrazione con altri servizi Azure
  • Funzionalità avanzate di sicurezza e conformità
  • Accesso a OpenAI e ad altri modelli di AI tramite Azure
  • Organizzazioni con abbonamenti Azure esistenti
Considerazioni:
  • Richiede un abbonamento Azure e la configurazione di Microsoft Foundry
  • Richiede una maggiore configurazione (URL dell’endpoint con percorso completo, nome del modello, versione dell’API)
  • I modelli disponibili possono differire da quelli accessibili direttamente tramite OpenAI
  • L’URL deve includere il percorso completo: /openai/deployments/[model-name]/chat/completions?api-version=...
  • Può offrire funzionalità specializzate e hosting di modelli personalizzati

​
Risorse aggiuntive

Hai completato correttamente le seguenti operazioni:
  • ✅ Accesso alle impostazioni di Configuration
  • ✅ Apertura di Connections management
  • ✅ Aggiunta di una nuova connessione LLM
  • ✅ Configurazione delle credenziali e delle impostazioni della connessione
  • ✅ Test della connessione
  • ✅ Acquisizione delle nozioni per gestire le connessioni
La tua connessione LLM è ora pronta per abilitare funzionalità di IA avanzate nei tuoi Document Skill di ABBYY Vantage!