Vai al contenuto principale

​
Panoramica

Le connessioni LLM in ABBYY Vantage consentono di integrare potenti modelli linguistici di provider come OpenAI e Microsoft Foundry direttamente nei flussi di lavoro di elaborazione dei documenti. Queste connessioni permettono ai tuoi Document Skills di sfruttare l’IA all’avanguardia per un’estrazione, classificazione e comprensione più accurate di documenti complessi. Cosa potrai fare:
  • Accedere alla configurazione di Connections
  • Aggiungere una nuova connessione LLM
  • Configurare le credenziali e le impostazioni della connessione
  • Testare la connessione
Tempo richiesto: 10-15 minuti Provider LLM supportati:
  • OpenAI ChatGPT
  • Microsoft Foundry
Nota: Al momento le connessioni LLM possono essere usate nei Document Skills solo tramite ABBYY Advanced Designer.

​
Prerequisiti

Prima di iniziare, assicurati di disporre di:
  1. Accesso come amministratore alla configurazione di ABBYY Vantage.
  2. Credenziali API del provider LLM selezionato:
    • 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. Una sottoscrizione attiva con il tuo provider LLM.
Nota: Le connessioni LLM sono gestite a livello di tenant e possono essere utilizzate da tutti i progettisti di Skill della tua organizzazione. Al momento, le connessioni LLM possono essere integrate nelle Document skill solo tramite ABBYY Advanced Designer.

​
Passaggio 1: accedere alle impostazioni di configurazione

Passa 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 che lavoreremo)
  • Identity Provider
  • Public API Client
  • Security Log
  • Environment Variables
  • IP Restrictions

​
Passaggio 2: Vai a Connections

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

​
Passaggio 3: Aggiungere una nuova connessione LLM

Avvia la procedura per creare una nuova connessione con il tuo provider LLM.
  1. Fai 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 alle API di OpenAI
    • Microsoft Foundry - OpenAI e altri modelli di intelligenza artificiale ospitati sull’infrastruttura Azure di Microsoft
  3. Seleziona il provider desiderato (in questo esempio useremo Microsoft Foundry).
  4. Fai clic su Next.
Nota: Ogni provider ha requisiti di configurazione diversi. Scegli il provider che corrisponde all’abbonamento LLM della tua organizzazione.

​
Passaggio 4: Configura i dettagli della connessione

Inserisci le informazioni richieste per la connessione al tuo LLM. Configurazione della connessione

​
Impostazioni generali

Nome
  • Un identificatore univoco per questa connessione
  • Esempio: Microsoft Foundry oppure Production GPT-4
  • Questo nome verrà visualizzato quando si selezionano le connessioni nei Document skill.
Descrizione
  • Facoltativa ma consigliata.
  • Fornisci un contesto utile sulla connessione.
  • Esempio: “Connessione Microsoft Foundry 1” oppure “API di produzione GPT-4”.
  • Importante: non includere credenziali sensibili nella descrizione.
Nota: Scegli nomi descrittivi che aiutino gli Skill Designer a capire quale connessione utilizzare per scopi diversi.

​
Impostazioni di connessione

I field obbligatori dipendono dal provider LLM utilizzato:

​
Per Microsoft Foundry:

Api Key
  • La chiave API di Microsoft Foundry dal portale Azure.
  • Puoi trovarla in: Azure Portal → La tua risorsa Microsoft Foundry → Keys and Endpoint.
  • Formato: una lunga stringa alfanumerica.
  • Segnaposto di esempio: [API Key Here]
Url
  • L’endpoint URL di Microsoft Foundry.
  • Puoi trovarlo in: Azure Portal → La tua risorsa Microsoft Foundry → 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 → La tua risorsa Microsoft Foundry → Deployments.
  • Esempio: gpt-4.1-nano, gpt-35-turbo, gpt-4
  • Questo deve corrispondere esattamente al nome del deployment.

​
Per OpenAI ChatGPT:

API key
  • La tua API key di OpenAI da platform.openai.com.
  • Puoi trovarla in: OpenAI Platform → API Keys.
  • Formato: inizia con sk-
Modello
  • Il modello specifico da utilizzare (ad es. gpt-4, gpt-3.5-turbo)
Attenzione: Non condividere mai le API key e non includerle nelle descrizioni. Queste credenziali consentono l’accesso ai tuoi servizi LLM e ai relativi costi.

​
Passaggio 5: Verificare la connessione

Verificare che la connessione sia configurata correttamente prima di salvare.
  1. Dopo aver inserito tutte le informazioni richieste, fare clic sul pulsante Test.
Testing Connection
  1. Vantage tenterà di connettersi al provider LLM utilizzando le credenziali fornite.
  2. Controllare il risultato del test:
    • Esito positivo (segno di spunta verde): La connessione funziona correttamente.
    • Esito negativo (X rossa o messaggio di errore): Verificare le credenziali e riprovare.

​
Risultati del test

Test riuscito:
  • Viene visualizzato un segno di spunta verde accanto alla connessione.
  • Ora puoi salvare la connessione.
  • La connessione è pronta per essere utilizzata nelle Document Skills.
Test non riuscito:
  • Controlla il messaggio di errore per individuare i problemi specifici.
  • Problemi comuni:
    • API key errata
    • URL dell’endpoint non valido
    • Nome del modello errato
    • Problemi di connettività di rete
    • Autorizzazioni insufficienti o superamento della quota
Nota: Esegui sempre un test della connessione prima di salvarla. In questo modo ti assicuri che le tue Document Skills possano utilizzare correttamente il provider LLM.

​
Passaggio 6: Salva la connessione

Finalizza la configurazione della connessione.
  1. Una volta che il test ha esito positivo, fai clic sul pulsante Add.
  2. La connessione ora compare nell’elenco Connections.
  3. La connessione è immediatamente disponibile per tutti gli Skill Designer nel tuo tenant.
La pagina Connections ora mostra:
  • Connection name: Come specificato
  • Description: La tua descrizione esplicativa
  • Used in Skills: Mostrerà quali skill utilizzano questa connessione
  • Last Updated: Data e ora correnti

​
Gestione delle connessioni esistenti

È possibile gestire le connessioni dopo la loro creazione.

​
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 approfonditi 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 verificare le credenziali.

​
Eliminare una connessione

  1. Selezionare la connessione dall’elenco.
  2. Fare clic sul pulsante Delete (icona del cestino).
  3. Confermare l’eliminazione.
Avviso: Non è possibile eliminare una connessione che è attualmente in uso in skill attive. Rimuovere prima la connessione da tutte le skill.

​
Risoluzione dei problemi

​
Test di connessione non riuscito

Problema: Il test di connessione restituisce un errore. Soluzioni:
  • API key non valida:
    • Verifica di aver copiato correttamente l’intera chiave.
    • Controlla che non ci siano spazi o caratteri aggiuntivi.
    • Se necessario, rigenera la chiave nel portale del tuo provider.
  • Endpoint URL non valido:
    • Assicurati che l’URL sia completo e formattato correttamente.
    • Verifica che l’URL corrisponda alla tua risorsa Azure.
    • Controlla eventuali errori di battitura nel percorso di deployment.
  • Nome del modello errato:
    • Conferma che il deployment esista nel tuo portale Azure.
    • Controlla l’ortografia e l’uso di maiuscole e minuscole (il nome è case-sensitive).
    • Verifica che il deployment sia attivo e disponibile.
  • Problemi di rete:
    • Controlla la tua connettività a Internet.
    • Verifica che le impostazioni del firewall consentano connessioni HTTPS in uscita.
    • Conferma che la tua istanza Vantage possa raggiungere il provider LLM.
  • Quota o autorizzazioni:
    • Verifica che il tuo abbonamento sia attivo.
    • Controlla di non aver superato i limiti di frequenza delle richieste (rate limit).
    • Assicurati che la tua API key disponga delle autorizzazioni necessarie.

​
La connessione funziona nel test ma non nelle Skill

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

​
Costi API più alti del previsto

Problema: Addebiti imprevisti dal fornitore del tuo LLM. Soluzioni:
  • Esaminare quali skill utilizzano la connessione.
  • Controllare i volumi e la frequenza di elaborazione.
  • Valutare l’implementazione di un meccanismo di limitazione della frequenza delle richieste (rate limiting).
  • Monitorare l’utilizzo tramite il dashboard del fornitore.
  • Usare modelli più convenienti dal punto di vista dei costi per i test.

​
Buone pratiche

​
Sicurezza

  • Non condividere mai le chiavi API in email o chat in chiaro.
  • Ruota regolarmente le credenziali (consigliato ogni 90 giorni).
  • Usa connessioni separate per l’ambiente di sviluppo e quello di produzione.
  • Monitora i log di accesso nella dashboard del provider LLM.
  • Applica il principio del minimo privilegio: concedi solo le autorizzazioni necessarie.
  • Conserva le credenziali di backup in modo sicuro per le situazioni di emergenza.

​
Gestione delle connessioni

  • Usa nomi descrittivi che indichino lo scopo o l’ambiente.
    • Esempi validi: “Production GPT-4”, “Development Microsoft Foundry”
    • Evita: “Connection 1”, “Test”
  • Documenta nelle descrizioni a cosa serve ciascuna connessione
    • Includi: ambiente, caso d’uso, contatto del referente
    • Escludi: credenziali, informazioni sensibili
  • Verifica regolarmente le connessioni per individuare i problemi in anticipo
    • Imposta una revisione mensile.
    • Effettua un test dopo ogni 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 i modelli appropriati per ogni caso d’uso.
    • Usa modelli più piccoli e veloci per attività semplici.
    • Riserva i modelli avanzati alle estrazioni complesse.
  • Implementa il rate limiting se il tuo provider lo supporta.
    • Previene picchi di costo imprevisti.
    • Protegge da elaborazioni fuori controllo.
  • Monitora i pattern di utilizzo
    • Configura avvisi di fatturazione nella dashboard del tuo provider.
    • Esamina costi e utilizzo mensili.
  • Ottimizza i prompt nelle tue Document Skills.
    • Prompt efficienti riducono il consumo di token.
    • Testa e perfeziona per ottenere i risultati migliori al costo più basso.

​
Ottimizzazione del flusso di lavoro

  • Raggruppa i tipi di documento simili
  • Configura Document skill appropriate per il tuo caso d’uso
  • Esegui test con documenti di esempio prima dell’uso in produzione
  • Documenta il tuo 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 con una sola chiave API
  • Organizzazioni che già utilizzano la piattaforma OpenAI
Considerazioni:
  • I dati vengono elaborati dall’infrastruttura di OpenAI
  • Soggetto ai termini e alle policy sui dati di OpenAI
  • Richiede un account OpenAI e l’accesso alle API

​
Microsoft Foundry

Ideale per:
  • Implementazioni aziendali 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 sottoscrizioni Azure già esistenti
Considerazioni:
  • Richiede una sottoscrizione Azure e la configurazione di Microsoft Foundry
  • Richiede una configurazione più articolata (endpoint URL 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:
  • ✅ Aperto le impostazioni di Configuration
  • ✅ Navigato alla sezione Connections management
  • ✅ Aggiunto una nuova connessione LLM
  • ✅ Configurato credenziali e impostazioni della connessione
  • ✅ Verificato la connessione
  • ✅ Imparato a gestire le connessioni
La tua connessione LLM è ora pronta per abilitare funzionalità di intelligenza artificiale avanzate nelle tue Document Skill di ABBYY Vantage!