Panoramica
- Accedere alla configurazione delle Connections
- Aggiungere una nuova connessione LLM
- Configurare le credenziali e le impostazioni della connessione
- Testare la connessione
- OpenAI ChatGPT
- Microsoft Foundry
Prerequisiti
- Accesso come amministratore alla configurazione di ABBYY Vantage.
- Credenziali API del provider LLM selezionato:
- OpenAI: chiave API del tuo account OpenAI
- Microsoft Foundry: chiave API, URL completo dell’endpoint (inclusi il percorso
/chat/completionse la versione dell’API) e nome del modello da Microsoft Foundry in Azure.
- Sottoscrizione attiva con il tuo provider LLM.
Passaggio 1: Accedere alle impostazioni di Configuration
- Nell’interfaccia di ABBYY Vantage, individua la sezione ADMIN nella barra laterale sinistra.
- Fai clic su Configuration (icona a forma di ingranaggio).
- General
- Connections (è qui che lavoreremo)
- Identity Provider
- Public API Client
- Security Log
- Environment Variables
- IP Restrictions
Accedi all’interfaccia di gestione di Connections.
- Nel menu Configuration a sinistra, fai clic su Connections.
- 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
Passaggio 3: Aggiungere una nuova connessione LLM
- Fare clic sul pulsante + Add Connection nella parte superiore della pagina Connections.
- 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
- Selezionare il provider desiderato (in questo esempio, useremo Microsoft Foundry).
- Fare clic su Next.
Passaggio 4: Configura i dettagli della connessione
Impostazioni generali
- Un identificatore univoco per questa connessione
- Esempio:
Microsoft FoundryoppureProduction GPT-4 - Questo nome verrà visualizzato quando si selezionano le connessioni nelle Document Skills.
- 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.
Impostazioni di connessione
Per Microsoft Foundry:
- La tua chiave API di Microsoft Foundry dal portale di Azure.
- Puoi trovarla in: Azure Portal → Your Microsoft Foundry Resource → Keys and Endpoint.
- Formato: una lunga stringa alfanumerica.
- Segnaposto di esempio:
[API Key Here]
- 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
- 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 - Deve corrispondere esattamente al tuo deployment.
Per OpenAI ChatGPT:
- La tua chiave API OpenAI da platform.openai.com.
- Puoi trovarla in: OpenAI Platform → API Keys.
- Formato: inizia con
sk-
- Il modello specifico da usare (ad es.
gpt-4,gpt-3.5-turbo)
Passaggio 5: test della connessione
- Dopo aver inserito tutte le informazioni richieste, fai clic sul pulsante Test.
- Vantage tenterà di connettersi al tuo provider di LLM utilizzando le credenziali che hai fornito.
- Controlla il risultato del test:
- Success (green checkmark): La connessione funziona correttamente.
- Failure (red X or error message): Controlla le credenziali e riprova.
Risultati del test
- Un segno di spunta verde viene visualizzato accanto alla connessione.
- Ora puoi salvare la connessione.
- La connessione è pronta per essere utilizzata nelle Document skill.
- Esamina il messaggio di errore per individuare eventuali problemi specifici.
- Problemi comuni:
- API key non corretta
- URL dell’endpoint non valido
- Nome del modello errato
- Problemi di connettività di rete
- Autorizzazioni o quota insufficienti
Passaggio 6: Salva la connessione
- Una volta che il test ha esito positivo, fai clic sul pulsante Add.
- La tua connessione ora viene visualizzata nell’elenco delle connessioni.
- La connessione è immediatamente disponibile per tutti i progettisti di Skill nel tuo tenant.
- Connection name: come specificato
- Description: la tua descrizione informativa
- Used in Skills: mostrerà quali skill stanno utilizzando questa connessione
- Last Updated: data e ora correnti
Gestione delle connessioni esistenti
Modificare una connessione
- Selezionare la connessione dall’elenco.
- Fare clic sul pulsante Edit (icona a forma di matita).
- Aggiornare i field necessari.
- Testare nuovamente la connessione.
- Fare clic su Save.
Verificare una connessione
- Seleziona la connessione dall’elenco.
- Fai clic sul pulsante Test (icona di aggiornamento).
- Verifica che la connessione sia ancora attiva.
- Questa operazione è utile per la risoluzione dei problemi o per verificare le credenziali.
Eliminare una connessione
- Selezionare la connessione dall’elenco.
- Fare clic sul pulsante Delete (icona del cestino).
- Confermare l’eliminazione.
Risoluzione dei problemi
Test di connessione non riuscito
- API key non valida:
- Verifica di aver copiato correttamente l’intera chiave.
- Controlla la presenza di spazi o caratteri in eccesso.
- 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 ortografia e uso di maiuscole/minuscole (il campo è 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.
- Conferma che la tua istanza Vantage possa raggiungere il provider di 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 abbia le autorizzazioni necessarie.
La connessione funziona nel test ma non nelle skill
- Aggiorna la pagina di Skill Designer.
- Seleziona nuovamente 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 delle API più alti del previsto
- Esamina quali Skill stanno usando la connessione.
- Verifica il volume e la frequenza di elaborazione.
- Valuta di implementare una limitazione della frequenza delle richieste (rate limiting).
- Monitora l’utilizzo tramite la dashboard del provider.
- Usa modelli più economici per i test.
Procedure consigliate
Sicurezza
- Non condividere mai le chiavi API via email o chat in chiaro.
- Ruota regolarmente le credenziali (si consiglia ogni 90 giorni).
- Usa connessioni separate per sviluppo e produzione.
- Monitora i log di accesso nella dashboard del tuo provider LLM.
- Implementa il principio del minimo privilegio: concedi solo le autorizzazioni necessarie.
- Archivia le credenziali di backup in modo sicuro per i casi di emergenza.
Gestione delle connessioni
- Usa nomi descrittivi che indichino lo scopo o l’ambiente.
- Esempi validi: “Produzione GPT-4”, “Sviluppo Microsoft Foundry”
- Da evitare: “Connessione 1”, “Test”
- Documenta nelle descrizioni a cosa serve ogni connessione
- Includi: ambiente, caso d’uso, contatto del responsabile
- 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.
- Tieni traccia dell’utilizzo per capire quali connessioni sono attive
- Controlla la colonna “Usata nelle Skill”.
- 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.
- Riserva i modelli avanzati per estrazioni complesse.
- Implementa il rate limiting se supportato dal tuo provider.
- Previene improvvisi picchi di costo.
- Protegge da elaborazioni fuori controllo.
- Monitora i modelli di utilizzo
- Configura avvisi di fatturazione nella dashboard del tuo provider.
- Esamina mensilmente costi e consumi.
- Ottimizza i prompt nelle tue Document Skills.
- Prompt efficienti riducono il consumo di token.
- Esegui test e perfeziona per ottenere i migliori risultati al costo più basso.
Ottimizzazione del flusso di lavoro
- Raggruppa tipi di documento simili
- Configura le Document skill appropriate per il tuo 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
- Accesso diretto ai modelli OpenAI più recenti
- Configurazione semplice con la sola chiave API
- Organizzazioni che già utilizzano la piattaforma OpenAI
- I dati vengono elaborati dall’infrastruttura di OpenAI
- È soggetto ai termini e alle politiche sui dati di OpenAI
- Richiede un account OpenAI e l’accesso alle API
Microsoft Foundry
- Distribuzioni 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 sottoscrizioni Azure esistenti
- Richiede una sottoscrizione Azure e la configurazione di Microsoft Foundry
- Necessita di una configurazione più complessa (endpoint URL con percorso completo, nome del modello, versione dell’API)
- I modelli disponibili possono differire da quelli dell’accesso diretto a 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
- Documentazione OpenAI API: https://platform.openai.com/docs
- Microsoft Foundry: https://azure.microsoft.com/products/ai-foundry
- Documentazione Azure AI Services: https://learn.microsoft.com/azure/ai-services/
- Supporto: contatta il supporto ABBYY per assistenza tecnica
Riepilogo
- ✅ Accesso alle impostazioni di Configuration
- ✅ Navigazione alla gestione di Connections
- ✅ Aggiunta di una nuova connessione LLM
- ✅ Configurazione delle credenziali e delle impostazioni della connessione
- ✅ Test della connessione
- ✅ Hai imparato a gestire le connessioni