Condividi tramite

Guida introduttiva: Chattare con i modelli OpenAI di Azure usando i propri dati

Annotazioni

Questo documento fa riferimento al portale di Microsoft Foundry (versione classica).

🔍Per informazioni sul nuovo portale, vedere la documentazione di Microsoft Foundry (nuova).

In questa guida introduttiva si usano i propri dati con i modelli OpenAI di Azure per creare una piattaforma di intelligenza artificiale conversazionale potente che consenta comunicazioni più veloci e accurate.

Importante

Esistono nuovi modi per creare soluzioni conversazionali con i propri dati. Per l'approccio consigliato più recente, vedere Guida introduttiva: Usare il recupero agentico in Azure AI Search.

Prerequisiti

  • Scaricare i dati di esempio da GitHub se non si hanno dati personalizzati.

Aggiungere i dati usando il portale di Microsoft Foundry

Suggerimento

In alternativa, è possibile usare l'Azure Developer CLI per creare programmaticamente le risorse necessarie per Azure OpenAI sui tuoi dati.

Per aggiungere i dati usando il portale:

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia disattivato. Questi passaggi fanno riferimento a Foundry (versione classica).

  2. Selezionare la risorsa Azure OpenAI. Se si dispone di una risorsa Foundry, è possibile creare un progetto Foundry.

  3. Nel riquadro sinistro selezionare Playgrounds>Chat.

  4. Nel riquadro Installazione selezionare la distribuzione del modello.

  5. Selezionare Aggiungi dati>Aggiungi un'origine dati.

    Un'istantanea del playground della chat su Foundry.

  6. Nella pagina Origine dati :

    1. In Seleziona origine dati, seleziona Carica file (anteprima).

      Suggerimento

    2. La condivisione di risorse tra le origini (CORS) è necessaria per l'accesso all'account di archiviazione di Azure OpenAI. Se CORS non è già abilitato per la risorsa di Archiviazione BLOB di Azure, selezionare Attiva CORS.

    3. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure.

    4. Immettere un nome per il nuovo indice.

    5. Selezionare la casella di controllo che accetta gli effetti di fatturazione dell'uso di Azure AI Search.

    6. Seleziona Avanti.

    Un screenshot che mostra le opzioni per la selezione di un'origine dati nel portale Foundry.

  7. Nella pagina Carica file :

    1. Selezionare Sfoglia un file e quindi selezionare i propri dati o i dati di esempio scaricati dai prerequisiti.

    2. Selezionare Carica file.

    3. Seleziona Avanti.

  8. Nella pagina Gestione dati :

    1. Scegliere se abilitare la ricerca semantica o la ricerca vettoriale per l'indice.

      Importante

      • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. Per abilitare la ricerca semantica o vettoriale, la risorsa di Ricerca di intelligenza artificiale di Azure deve essere al livello Basic o superiore. Per altre informazioni, vedere Scegliere un livello e limiti del servizio.
      • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, Germania, cinese(Zh), giapponese, coreano, russo e arabo.

    2. Seleziona Avanti.

  9. Nella pagina Connessione dati :

    1. Scegliere se eseguire l'autenticazione usando un'identità gestita assegnata dal sistema o una chiave API.

    2. Seleziona Avanti.

  10. Esaminare le configurazioni e quindi selezionare Salva e chiudi.

    È ora possibile chattare con il modello, che usa i dati per costruire la risposta.

Playground della chat

Iniziare a esplorare le funzionalità di Azure OpenAI con un approccio senza codice tramite il playground chat. Si tratta semplicemente di una casella di testo in cui è possibile inviare una richiesta di generazione di un completamento. Da questa pagina è possibile eseguire rapidamente l'iterazione e sperimentare le funzionalità.

Screenshot della pagina playground del portale di Microsoft Foundry con le sezioni evidenziate.

Il playground offre opzioni per personalizzare l'esperienza di chat. Nel menu in alto è possibile selezionare Distribuisci per determinare quale modello genera una risposta usando i risultati della ricerca dall'indice. Si sceglie il numero di messaggi passati da includere come cronologia delle conversazioni per le risposte generate in futuro. La cronologia conversazioni fornisce contesto per generare risposte correlate, ma utilizza anche l’utilizzo dei token. L'indicatore di stato del token di input tiene traccia del numero di token della domanda inviata.

Le impostazioni avanzate a sinistra sono parametri di runtime che consentono di controllare il recupero e la ricerca delle informazioni pertinenti dai dati. Un caso d'uso valido è quello in cui ci si vuole assicurare che le risposte vengano generate solo in base ai propri dati o si scopre che il modello non può generare una risposta in base alle informazioni esistenti sui propri dati.

  • Il Rigore determina l'aggressività del sistema nell'applicazione di filtri ai documenti di ricerca in base ai punteggi di somiglianza. L'impostazione di rigore su 5 indica che il sistema filtra in modo aggressivo i documenti, applicando una soglia di somiglianza molto elevata. La ricerca semantica può essere utile in questo scenario perché i modelli di classificazione eseguono un lavoro migliore per dedurre la finalità della query. I livelli più bassi di rigidità producono risposte più dettagliate, ma possono includere anche informazioni che non si trovano nell'indice. Questa opzione è impostata su 3 per impostazione predefinita.

  • I Documenti recuperatisono un numero intero che può essere impostato su 3, 5, 10 o 20 e controlla il numero di blocchi di documento forniti al modello linguistico di grandi dimensioni per simulare la risposta finale. Per impostazione predefinita, il valore è impostato su 5.

  • Quando Limitare le risposte ai dati è abilitato, il modello tenta di basarsi solo sui documenti per le risposte. Questa proprietà è impostata su true per impostazione predefinita.

Screenshot delle impostazioni avanzate.

Inviare la prima query. I modelli di chat eseguono al meglio esercizi di domande e risposte. Ad esempio, "Quali sono i piani di integrità disponibili?" o "Qual è l'opzione di integrità più?".

Le query che richiedono l'analisi dei dati potrebbero avere esito negativo, ad esempio "Quale piano di integrità è più diffuso?". Anche le query che richiedono informazioni su tutti i dati avranno esito negativo, ad esempio "Quanti documenti sono stati caricati?". Tenere presente che il motore di ricerca cerca blocchi con termini, frasi o costruzione esatti o simili alla query. Mentre il modello potrebbe comprendere la domanda, se i risultati della ricerca sono blocchi dal set di dati, non sono le informazioni corrette per rispondere a quel tipo di domanda.

Le chat sono vincolate dal numero di documenti (blocchi) restituiti nella risposta (limitato a 3-20 nel playground del portale Fonderia). Come si può immaginare, porre una domanda su "tutti i titoli" richiede un'analisi completa dell'intero archivio vettoriale.

Distribuire il modello

Una volta che sei soddisfatto dell'esperienza, puoi pubblicare un'app Web direttamente dal portale selezionando il pulsante Distribuisci in.

Screenshot che mostra il pulsante di distribuzione del modello nel portale.

In questo modo è possibile eseguire la distribuzione in un'applicazione Web autonoma o un copilota in Copilot Studio (anteprima) se si usando i propri dati nel modello.

Ad esempio, se si sceglie di distribuire un'app Web:

La prima volta che si distribuisce un'app Web, è necessario selezionare Crea una nuova app Web. Scegliere un nome per l'app, che diventerà parte del suo URL. Ad esempio: https://<appname>.azurewebsites.net.

Selezionare la sottoscrizione, il gruppo di risorse, la località e il piano tariffario per l'app pubblicata. Per aggiornare un'app esistente, selezionare Pubblica in un'app Web esistente e scegliere il nome dell'app precedente dal menu a discesa.

Se si sceglie di distribuire un'app Web, vedere le considerazioni importanti per l'uso.

Prerequisiti

Aggiungere i dati usando il portale di Microsoft Foundry

Suggerimento

In alternativa, è possibile usare l'Azure Developer CLI per creare programmaticamente le risorse necessarie per Azure OpenAI sui tuoi dati.

Per aggiungere i dati usando il portale:

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia disattivato. Questi passaggi fanno riferimento a Foundry (versione classica).

  2. Selezionare la risorsa Azure OpenAI. Se si dispone di una risorsa Foundry, è possibile creare un progetto Foundry.

  3. Nel riquadro sinistro selezionare Playgrounds>Chat.

  4. Nel riquadro Installazione selezionare la distribuzione del modello.

  5. Selezionare Aggiungi dati>Aggiungi un'origine dati.

    Un'istantanea del playground della chat su Foundry.

  6. Nella pagina Origine dati :

    1. In Seleziona origine dati, seleziona Carica file (anteprima).

      Suggerimento

    2. La condivisione di risorse tra le origini (CORS) è necessaria per l'accesso all'account di archiviazione di Azure OpenAI. Se CORS non è già abilitato per la risorsa di Archiviazione BLOB di Azure, selezionare Attiva CORS.

    3. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure.

    4. Immettere un nome per il nuovo indice.

    5. Selezionare la casella di controllo che accetta gli effetti di fatturazione dell'uso di Azure AI Search.

    6. Seleziona Avanti.

    Un screenshot che mostra le opzioni per la selezione di un'origine dati nel portale Foundry.

  7. Nella pagina Carica file :

    1. Selezionare Sfoglia un file e quindi selezionare i propri dati o i dati di esempio scaricati dai prerequisiti.

    2. Selezionare Carica file.

    3. Seleziona Avanti.

  8. Nella pagina Gestione dati :

    1. Scegliere se abilitare la ricerca semantica o la ricerca vettoriale per l'indice.

      Importante

      • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. Per abilitare la ricerca semantica o vettoriale, la risorsa di Ricerca di intelligenza artificiale di Azure deve essere al livello Basic o superiore. Per altre informazioni, vedere Scegliere un livello e limiti del servizio.
      • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, Germania, cinese(Zh), giapponese, coreano, russo e arabo.

    2. Seleziona Avanti.

  9. Nella pagina Connessione dati :

    1. Scegliere se eseguire l'autenticazione usando un'identità gestita assegnata dal sistema o una chiave API.

    2. Seleziona Avanti.

  10. Esaminare le configurazioni e quindi selezionare Salva e chiudi.

    È ora possibile chattare con il modello, che usa i dati per costruire la risposta.

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI di Azure. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati usando il portale di Microsoft Foundry.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Un endpoint di esempio è https://my-resource.openai.azure.com.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Dalla directory del progetto, aprire il file Program.cs e sostituire i contenuti con il codice seguente:

using System;
using Azure.AI.OpenAI;
using System.ClientModel;
using Azure.AI.OpenAI.Chat;
using OpenAI.Chat;
using static System.Environment;

string azureOpenAIEndpoint = GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
string azureOpenAIKey = GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
string deploymentName = GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME");
string searchEndpoint = GetEnvironmentVariable("AZURE_AI_SEARCH_ENDPOINT");
string searchKey = GetEnvironmentVariable("AZURE_AI_SEARCH_API_KEY");
string searchIndex = GetEnvironmentVariable("AZURE_AI_SEARCH_INDEX");

AzureOpenAIClient openAIClient = new(
			new Uri(azureOpenAIEndpoint),
			new ApiKeyCredential(azureOpenAIKey));
ChatClient chatClient = openAIClient.GetChatClient(deploymentName);

// Extension methods to use data sources with options are subject to SDK surface changes. Suppress the
// warning to acknowledge and this and use the subject-to-change AddDataSource method.
#pragma warning disable AOAI001

ChatCompletionOptions options = new();
options.AddDataSource(new AzureSearchChatDataSource()
{
	Endpoint = new Uri(searchEndpoint),
	IndexName = searchIndex,
	Authentication = DataSourceAuthentication.FromApiKey(searchKey),
});

ChatCompletion completion = chatClient.CompleteChat(
	[
		new UserChatMessage("What health plans are available?"),
			],
	options);

ChatMessageContext onYourDataContext = completion.GetMessageContext();

if (onYourDataContext?.Intent is not null)
{
	Console.WriteLine($"Intent: {onYourDataContext.Intent}");
}
foreach (ChatCitation citation in onYourDataContext?.Citations ?? [])
{
	Console.WriteLine($"Citation: {citation.Content}");
}

Importante

Per la produzione, utilizzare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere questo articolo sulla sicurezza .

dotnet run Program.cs

Risultato

Contoso Electronics offers two health plans: Northwind Health Plus and Northwind Standard [doc1]. Northwind Health Plus is a comprehensive plan that provides coverage for medical, vision, and dental services, prescription drug coverage, mental health and substance abuse coverage, and coverage for preventive care services. It also offers coverage for emergency services, both in-network and out-of-network. On the other hand, Northwind Standard is a basic plan that provides coverage for medical, vision, and dental services, prescription drug coverage, and coverage for preventive care services. However, it does not offer coverage for emergency services, mental health and substance abuse coverage, or out-of-network services [doc1].

Intent: ["What are the available health plans?", "List of health plans available", "Health insurance options", "Types of health plans offered"]

Citation:
Contoso Electronics plan and benefit packages

Thank you for your interest in the Contoso electronics plan and benefit packages. Use this document to

learn more about the various options available to you...// Omitted for brevity

Questa operazione attenderà fino a quando il modello non ha generato l'intera risposta prima di stampare i risultati.

Codice sorgente| Codice sorgente | Esempio

Prerequisiti

Aggiungere i dati usando il portale di Microsoft Foundry

Suggerimento

In alternativa, è possibile usare l'Azure Developer CLI per creare programmaticamente le risorse necessarie per Azure OpenAI sui tuoi dati.

Per aggiungere i dati usando il portale:

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia disattivato. Questi passaggi fanno riferimento a Foundry (versione classica).

  2. Selezionare la risorsa Azure OpenAI. Se si dispone di una risorsa Foundry, è possibile creare un progetto Foundry.

  3. Nel riquadro sinistro selezionare Playgrounds>Chat.

  4. Nel riquadro Installazione selezionare la distribuzione del modello.

  5. Selezionare Aggiungi dati>Aggiungi un'origine dati.

    Un'istantanea del playground della chat su Foundry.

  6. Nella pagina Origine dati :

    1. In Seleziona origine dati, seleziona Carica file (anteprima).

      Suggerimento

    2. La condivisione di risorse tra le origini (CORS) è necessaria per l'accesso all'account di archiviazione di Azure OpenAI. Se CORS non è già abilitato per la risorsa di Archiviazione BLOB di Azure, selezionare Attiva CORS.

    3. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure.

    4. Immettere un nome per il nuovo indice.

    5. Selezionare la casella di controllo che accetta gli effetti di fatturazione dell'uso di Azure AI Search.

    6. Seleziona Avanti.

    Un screenshot che mostra le opzioni per la selezione di un'origine dati nel portale Foundry.

  7. Nella pagina Carica file :

    1. Selezionare Sfoglia un file e quindi selezionare i propri dati o i dati di esempio scaricati dai prerequisiti.

    2. Selezionare Carica file.

    3. Seleziona Avanti.

  8. Nella pagina Gestione dati :

    1. Scegliere se abilitare la ricerca semantica o la ricerca vettoriale per l'indice.

      Importante

      • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. Per abilitare la ricerca semantica o vettoriale, la risorsa di Ricerca di intelligenza artificiale di Azure deve essere al livello Basic o superiore. Per altre informazioni, vedere Scegliere un livello e limiti del servizio.
      • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, Germania, cinese(Zh), giapponese, coreano, russo e arabo.

    2. Seleziona Avanti.

  9. Nella pagina Connessione dati :

    1. Scegliere se eseguire l'autenticazione usando un'identità gestita assegnata dal sistema o una chiave API.

    2. Seleziona Avanti.

  10. Esaminare le configurazioni e quindi selezionare Salva e chiudi.

    È ora possibile chattare con il modello, che usa i dati per costruire la risposta.

Recuperare variabili obbligatorie

Per eseguire correttamente una chiamata a OpenAI di Azure, sono necessarie le seguenti variabili. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Per altre informazioni, vedere Aggiungere i dati con Microsoft Foundry.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT È possibile trovare questo valore nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. In alternativa, è possibile trovare il valore in Fonderia>Playground chat>Visualizzazione codice. Un endpoint di esempio è https://my-resource.openai.azure.com.
AZURE_OPENAI_API_KEY È possibile trovare questo valore nella sezione Gestione delle risorse>Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. È possibile usare KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_OPEN_AI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. È possibile trovare questo valore sotto Gestione delle risorse>Distribuzioni nel portale di Azure o in alternativa sotto Gestione>Distribuzioni nel portale Foundry.
AZURE_AI_SEARCH_ENDPOINT È possibile trovare questo valore nella sezione Panoramica quando si esamina la risorsa Ricerca cognitiva di Azure dal portale di Azure.
AZURE_AI_SEARCH_API_KEY È possibile trovare questo valore nella sezione Impostazioni>Chiavi quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure. È possibile usare la chiave do amministrazione primaria o la chiave di amministrazione secondaria. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Utilizzare le chiavi API con cautela. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente. Se si usa una chiave API, archiviarla in modo sicuro in Azure Key Vault. Per altre informazioni sull'uso sicuro delle chiavi API nelle app, vedere Chiavi API con Azure Key Vault.

Per altre informazioni sulla sicurezza dei servizi di intelligenza artificiale, vedere Autenticare le richieste ai servizi di intelligenza artificiale di Azure.

Annotazioni

Spring AI imposta per impostazione predefinita il nome del modello su gpt-35-turbo. È necessario specificare il valore SPRING_AI_AZURE_OPENAI_MODEL solo se è stato distribuito un modello con un nome diverso.

export SPRING_AI_AZURE_OPENAI_ENDPOINT=REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE
export SPRING_AI_AZURE_OPENAI_API_KEY=REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE
export SPRING_AI_AZURE_COGNITIVE_SEARCH_ENDPOINT=REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE
export SPRING_AI_AZURE_COGNITIVE_SEARCH_API_KEY=REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE
export SPRING_AI_AZURE_COGNITIVE_SEARCH_INDEX=REPLACE_WITH_YOUR_INDEX_NAME_HERE
export SPRING_AI_AZURE_OPENAI_MODEL=REPLACE_WITH_YOUR_MODEL_NAME_HERE

Creare una nuova applicazione Spring

Spring AI non supporta attualmente le opzioni di AzureCognitiveSearchChatExtensionConfiguration che consentono a una query Azure AI di incapsulare il metodo di Recupero di generazione aumentata (RAG) e di nascondere i dettagli all'utente. In alternativa, è comunque possibile richiamare il metodo RAG direttamente nell'applicazione per eseguire query sui dati nell'indice di Ricerca intelligenza artificiale di Azure e usare i documenti recuperati per aumentare la query.

Spring AI supporta un'astrazione VectorStore ed è possibile eseguire il wrapping di Ricerca intelligenza artificiale di Azure in un'implementazione Spring AI VectorStore per eseguire query sui dati personalizzati. Il progetto seguente implementa un VectorStore personalizzato supportato da Ricerca di intelligenza artificiale di Azure ed esegue direttamente le operazioni RAG.

In una finestra Bash creare una nuova directory per l'app e passare a essa.

mkdir ai-custom-data-demo && cd ai-custom-data-demo

Esegui il comando spring init dalla tua directory di lavoro. Questo comando crea una struttura di directory standard per il progetto Spring, incluso il file di origine della classe Java principale e il file pom.xml usato per la gestione dei progetti basati su Maven.

spring init -a ai-custom-data-demo -n AICustomData --force --build maven -x

I file e le cartelle generati sono simili alla struttura seguente:

ai-custom-data-demo/
|-- pom.xml
|-- mvn
|-- mvn.cmd
|-- HELP.md
|-- src/
    |-- main/
    |   |-- resources/
    |   |   |-- application.properties
    |   |-- java/
    |       |-- com/
    |           |-- example/
    |               |-- aicustomdatademo/
    |                   |-- AiCustomDataApplication.java
    |-- test/
        |-- java/
            |-- com/
                |-- example/
                    |-- aicustomdatademo/
                        |-- AiCustomDataApplicationTests.java

Modificare l'applicazione Spring

  1. Modificare il file pom.xml.

    Dalla radice della directory del progetto aprire il file pom.xml nell'editor o nell'IDE preferito e sovrascrivere il file con il contenuto seguente:

    <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>ai-custom-data-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>AICustomData</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.experimental.ai</groupId>
            <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
            <version>0.7.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.6.0-beta.10</version>
            <exclusions>
                <!-- exclude this to avoid changing the default serializer and the null-value behavior -->
                <exclusion>
                    <groupId>com.azure</groupId>
                    <artifactId>azure-core-serializer-json-jackson</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
    <repositories>
        <repository>
            <id>spring-snapshots</id>
            <name>Spring Snapshots</name>
            <url>https://repo.spring.io/snapshot</url>
            <releases>
                <enabled>false</enabled>
            </releases>
        </repository>
    </repositories>
</project>

  2. Dalla cartella src/main/java/com/example/aicustomdatademo aprire AiCustomDataApplication.java nell'editor o nell'IDE preferito e incollare il codice seguente:

    package com.example.aicustomdatademo;

import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.stream.Collectors;

import org.springframework.ai.client.AiClient;
import org.springframework.ai.document.Document;
import org.springframework.ai.embedding.EmbeddingClient;
import org.springframework.ai.prompt.Prompt;
import org.springframework.ai.prompt.SystemPromptTemplate;
import org.springframework.ai.prompt.messages.MessageType;
import org.springframework.ai.prompt.messages.UserMessage;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.util.Context;
import com.azure.search.documents.SearchClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.models.IndexingResult;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.RawVectorQuery;

import lombok.AllArgsConstructor;
import lombok.NoArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.extern.jackson.Jacksonized;

@SpringBootApplication
public class AiCustomDataApplication implements CommandLineRunner
{
    private static final String ROLE_INFO_KEY = "role";

    private static final String template = """
            You are a helpful assistant. Use the information from the DOCUMENTS section to augment answers.

            DOCUMENTS:
            {documents}
            """;

    @Value("${spring.ai.azure.cognitive-search.endpoint}")
    private String acsEndpoint;

    @Value("${spring.ai.azure.cognitive-search.api-key}")
    private String acsApiKey;

    @Value("${spring.ai.azure.cognitive-search.index}")
    private String acsIndexName;

    @Autowired
    private AiClient aiClient;

    @Autowired
    private EmbeddingClient embeddingClient;

    public static void main(String[] args) {
        SpringApplication.run(AiCustomDataApplication.class, args);
    }

    @Override
    public void run(String... args) throws Exception
    {
        System.out.println(String.format("Sending custom data prompt to Foundry Tool. One moment please...\r\n"));

        final var store = vectorStore(embeddingClient);

        final String question = "What are my available health plans?";

        final var candidateDocs = store.similaritySearch(question);

        final var userMessage = new UserMessage(question);

        final String docPrompts =
                candidateDocs.stream().map(entry -> entry.getContent()).collect(Collectors.joining("\n"));

        final SystemPromptTemplate promptTemplate = new SystemPromptTemplate(template);
        final var systemMessage = promptTemplate.createMessage(Map.of("documents", docPrompts));

        final var prompt = new Prompt(List.of(systemMessage, userMessage));

        final var resps = aiClient.generate(prompt);

        System.out.println(String.format("Prompt created %d generated response(s).", resps.getGenerations().size()));

        resps.getGenerations().stream()
          .forEach(gen -> {
              final var role = gen.getInfo().getOrDefault(ROLE_INFO_KEY, MessageType.ASSISTANT.getValue());

              System.out.println(String.format("Generated respose from \"%s\": %s", role, gen.getText()));
          });

    }

    @Bean
    public VectorStore vectorStore(EmbeddingClient embeddingClient)
    {
        final SearchClient searchClient = new SearchClientBuilder()
                .endpoint(acsEndpoint)
                .credential(new AzureKeyCredential(acsApiKey))
                .indexName(acsIndexName)
                .buildClient();
        return new AzureCognitiveSearchVectorStore(searchClient, embeddingClient);
    }

    public static class AzureCognitiveSearchVectorStore implements VectorStore
    {
        private static final int DEFAULT_TOP_K = 4;

        private static final Double DEFAULT_SIMILARITY_THRESHOLD = 0.0;

        private SearchClient searchClient;

        private final EmbeddingClient embeddingClient;

        public AzureCognitiveSearchVectorStore(SearchClient searchClient, EmbeddingClient embeddingClient)
        {
            this.searchClient = searchClient;
            this.embeddingClient = embeddingClient;
        }

        @Override
        public void add(List<Document> documents)
        {
            final var docs = documents.stream().map(document -> {

                final var embeddings = embeddingClient.embed(document);

                return new DocEntry(document.getId(), "", document.getContent(), embeddings);

            }).toList();

            searchClient.uploadDocuments(docs);
        }

        @Override
        public Optional<Boolean> delete(List<String> idList)
        {
            final List<DocEntry> docIds = idList.stream().map(id -> DocEntry.builder().id(id).build())
                .toList();

            var results = searchClient.deleteDocuments(docIds);

            boolean resSuccess = true;

            for (IndexingResult result : results.getResults())
                if (!result.isSucceeded()) {
                    resSuccess = false;
                    break;
                }

            return Optional.of(resSuccess);
        }

        @Override
        public List<Document> similaritySearch(String query)
        {
            return similaritySearch(query, DEFAULT_TOP_K);
        }

        @Override
        public List<Document> similaritySearch(String query, int k)
        {
            return similaritySearch(query, k, DEFAULT_SIMILARITY_THRESHOLD);
        }

        @Override
        public List<Document> similaritySearch(String query, int k, double threshold)
        {
            final var searchQueryVector = new RawVectorQuery()
                    .setVector(toFloatList(embeddingClient.embed(query)))
                    .setKNearestNeighborsCount(k)
                    .setFields("contentVector");

            final var searchResults = searchClient.search(null,
                    new SearchOptions().setVectorQueries(searchQueryVector), Context.NONE);

            return searchResults.stream()
                    .filter(r -> r.getScore() >= threshold)
                    .map(r -> {

                        final DocEntry entry = r.getDocument(DocEntry.class);

                        final Document doc = new Document(entry.getId(), entry.getContent(), Collections.emptyMap());
                        doc.setEmbedding(entry.getContentVector());

                        return doc;
                    })
                    .collect(Collectors.toList());
        }

        private List<Float> toFloatList(List<Double> doubleList)
        {
            return doubleList.stream().map(Double::floatValue).toList();
        }

    }

    @Data
    @Builder
    @Jacksonized
    @AllArgsConstructor
    @NoArgsConstructor
    static class DocEntry
    {
        private String id;

        private String hash;

        private String content;

        private List<Double> contentVector;
    }

}

    Importante

    Per la produzione, utilizzare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere questo articolo sulla sicurezza .

  3. Tornare alla cartella radice del progetto ed eseguire l'app usando il comando seguente:

    ./mvnw spring-boot:run

Risultato

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.1.5)

2023-11-07T14:40:45.250-06:00  INFO 18557 --- [           main] c.e.a.AiCustomDataApplication            : No active profile set, falling back to 1 default profile: "default"
2023-11-07T14:40:46.035-06:00  INFO 18557 --- [           main] c.e.a.AiCustomDataApplication            : Started AiCustomDataApplication in 1.095 seconds (process running for 1.397)
Sending custom data prompt to Foundry Tool. One moment please...

Prompt created 1 generated response(s).
Generated response from "assistant": The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans.

Documentazione di riferimento | Codice sorgente | Pacchetto (npm) | Campioni

Prerequisiti

Prerequisiti di Microsoft Entra ID

Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, è necessario:

  • Installare l'Azure CLI utilizzata per l'autenticazione senza password con Microsoft Entra ID.
  • Assegna il ruolo Cognitive Services User al tuo account utente. È possibile assegnare ruoli nel portale di Azure in Controllo di accesso (IAM)>Aggiungere un'assegnazione di ruolo.

Aggiungere i dati usando il portale di Microsoft Foundry

Suggerimento

In alternativa, è possibile usare l'Azure Developer CLI per creare programmaticamente le risorse necessarie per Azure OpenAI sui tuoi dati.

Per aggiungere i dati usando il portale:

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia disattivato. Questi passaggi fanno riferimento a Foundry (versione classica).

  2. Selezionare la risorsa Azure OpenAI. Se si dispone di una risorsa Foundry, è possibile creare un progetto Foundry.

  3. Nel riquadro sinistro selezionare Playgrounds>Chat.

  4. Nel riquadro Installazione selezionare la distribuzione del modello.

  5. Selezionare Aggiungi dati>Aggiungi un'origine dati.

    Un'istantanea del playground della chat su Foundry.

  6. Nella pagina Origine dati :

    1. In Seleziona origine dati, seleziona Carica file (anteprima).

      Suggerimento

    2. La condivisione di risorse tra le origini (CORS) è necessaria per l'accesso all'account di archiviazione di Azure OpenAI. Se CORS non è già abilitato per la risorsa di Archiviazione BLOB di Azure, selezionare Attiva CORS.

    3. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure.

    4. Immettere un nome per il nuovo indice.

    5. Selezionare la casella di controllo che accetta gli effetti di fatturazione dell'uso di Azure AI Search.

    6. Seleziona Avanti.

    Un screenshot che mostra le opzioni per la selezione di un'origine dati nel portale Foundry.

  7. Nella pagina Carica file :

    1. Selezionare Sfoglia un file e quindi selezionare i propri dati o i dati di esempio scaricati dai prerequisiti.

    2. Selezionare Carica file.

    3. Seleziona Avanti.

  8. Nella pagina Gestione dati :

    1. Scegliere se abilitare la ricerca semantica o la ricerca vettoriale per l'indice.

      Importante

      • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. Per abilitare la ricerca semantica o vettoriale, la risorsa di Ricerca di intelligenza artificiale di Azure deve essere al livello Basic o superiore. Per altre informazioni, vedere Scegliere un livello e limiti del servizio.
      • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, Germania, cinese(Zh), giapponese, coreano, russo e arabo.

    2. Seleziona Avanti.

  9. Nella pagina Connessione dati :

    1. Scegliere se eseguire l'autenticazione usando un'identità gestita assegnata dal sistema o una chiave API.

    2. Seleziona Avanti.

  10. Esaminare le configurazioni e quindi selezionare Salva e chiudi.

    È ora possibile chattare con il modello, che usa i dati per costruire la risposta.

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI di Azure. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati usando il portale di Microsoft Foundry.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Un endpoint di esempio è https://my-resource.openai.azure.com.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Configurazione

  1. Creare una nuova cartella use-data-quickstart e passare alla cartella quickstart con il comando seguente:

    mkdir use-data-quickstart && cd use-data-quickstart

  2. Creare il package.json con il seguente comando:

    npm init -y

  3. Installare la libreria client OpenAI per JavaScript con:

    npm install openai

  4. Per l'autenticazione senza password consigliata:

    npm install @azure/identity

Aggiungere il codice JavaScript

  1. Creare il index.js file con il codice seguente:

    const { DefaultAzureCredential, getBearerTokenProvider } = require("@azure/identity");
const { AzureOpenAI } = require("openai");

// Set the Azure and AI Search values from environment variables
const endpoint = process.env.AZURE_OPENAI_ENDPOINT || "Your endpoint";
const searchEndpoint = process.env.AZURE_AI_SEARCH_ENDPOINT || "Your search endpoint";
const searchIndex = process.env.AZURE_AI_SEARCH_INDEX || "Your search index";

// keyless authentication    
const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

// Required Azure OpenAI deployment name and API version
const deploymentName = process.env.AZURE_OPENAI_DEPLOYMENT_NAME || "gpt-4";
const apiVersion = process.env.OPENAI_API_VERSION || "2024-10-21";

function getClient() {
  return new AzureOpenAI({
    endpoint,
    azureADTokenProvider,
    deployment: deploymentName,
    apiVersion,
  });
}

async function main() {
  const client = getClient();

  const messages = [
    { role: "user", content: "What are my available health plans?" },
  ];

  console.log(`Message: ${messages.map((m) => m.content).join("\n")}`);

  const events = await client.chat.completions.create({
    stream: true,
    messages: [
      {
        role: "user",
        content:
          "What's the most common feedback we received from our customers about the product?",
      },
    ],
    max_tokens: 128,
    model: "",
    data_sources: [
      {
        type: "azure_search",
        parameters: {
          endpoint: searchEndpoint,
          index_name: searchIndex,
          authentication: {
            type: "api_key",
            key: searchKey,
          },
        },
      },
    ],
  });

  let response = "";
  for await (const event of events) {
    for (const choice of event.choices) {
      const newText = choice.delta?.content;
      if (newText) {
        response += newText;
        // To see streaming results as they arrive, uncomment line below
        // console.log(newText);
      }
    }
  }
  console.log(response);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

  2. Accedere ad Azure con il comando seguente:

    az login

  3. Eseguire il file JavaScript.

    node index.js

Risultato

Message: What are my available health plans?
The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans.

Documentazione di riferimento | Codice sorgente | Pacchetto (npm) | Campioni

Prerequisiti

Prerequisiti di Microsoft Entra ID

Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, è necessario:

  • Installare l'Azure CLI utilizzata per l'autenticazione senza password con Microsoft Entra ID.
  • Assegna il ruolo Cognitive Services User al tuo account utente. È possibile assegnare ruoli nel portale di Azure in Controllo di accesso (IAM)>Aggiungere un'assegnazione di ruolo.

Aggiungere i dati usando il portale di Microsoft Foundry

Suggerimento

In alternativa, è possibile usare l'Azure Developer CLI per creare programmaticamente le risorse necessarie per Azure OpenAI sui tuoi dati.

Per aggiungere i dati usando il portale:

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia disattivato. Questi passaggi fanno riferimento a Foundry (versione classica).

  2. Selezionare la risorsa Azure OpenAI. Se si dispone di una risorsa Foundry, è possibile creare un progetto Foundry.

  3. Nel riquadro sinistro selezionare Playgrounds>Chat.

  4. Nel riquadro Installazione selezionare la distribuzione del modello.

  5. Selezionare Aggiungi dati>Aggiungi un'origine dati.

    Un'istantanea del playground della chat su Foundry.

  6. Nella pagina Origine dati :

    1. In Seleziona origine dati, seleziona Carica file (anteprima).

      Suggerimento

    2. La condivisione di risorse tra le origini (CORS) è necessaria per l'accesso all'account di archiviazione di Azure OpenAI. Se CORS non è già abilitato per la risorsa di Archiviazione BLOB di Azure, selezionare Attiva CORS.

    3. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure.

    4. Immettere un nome per il nuovo indice.

    5. Selezionare la casella di controllo che accetta gli effetti di fatturazione dell'uso di Azure AI Search.

    6. Seleziona Avanti.

    Un screenshot che mostra le opzioni per la selezione di un'origine dati nel portale Foundry.

  7. Nella pagina Carica file :

    1. Selezionare Sfoglia un file e quindi selezionare i propri dati o i dati di esempio scaricati dai prerequisiti.

    2. Selezionare Carica file.

    3. Seleziona Avanti.

  8. Nella pagina Gestione dati :

    1. Scegliere se abilitare la ricerca semantica o la ricerca vettoriale per l'indice.

      Importante

      • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. Per abilitare la ricerca semantica o vettoriale, la risorsa di Ricerca di intelligenza artificiale di Azure deve essere al livello Basic o superiore. Per altre informazioni, vedere Scegliere un livello e limiti del servizio.
      • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, Germania, cinese(Zh), giapponese, coreano, russo e arabo.

    2. Seleziona Avanti.

  9. Nella pagina Connessione dati :

    1. Scegliere se eseguire l'autenticazione usando un'identità gestita assegnata dal sistema o una chiave API.

    2. Seleziona Avanti.

  10. Esaminare le configurazioni e quindi selezionare Salva e chiudi.

    È ora possibile chattare con il modello, che usa i dati per costruire la risposta.

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI di Azure. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati usando il portale di Microsoft Foundry.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Un endpoint di esempio è https://my-resource.openai.azure.com.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Configurazione

  1. Creare una nuova cartella use-data-quickstart e passare alla cartella quickstart con il comando seguente:

    mkdir use-data-quickstart && cd use-data-quickstart

  2. Creare il package.json con il seguente comando:

    npm init -y

  3. Aggiornare package.json a ECMAScript con il comando seguente:

    npm pkg set type=module

  4. Installare la libreria client OpenAI per JavaScript con:

    npm install openai

  5. Per l'autenticazione senza password consigliata:

    npm install @azure/identity

Aggiungere il codice TypeScript

  1. Creare il index.ts file con il codice seguente:

    import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import "@azure/openai/types";

// Set the Azure and AI Search values from environment variables
const endpoint = process.env.AZURE_OPENAI_ENDPOINT || "Your endpoint";
const searchEndpoint = process.env.AZURE_AI_SEARCH_ENDPOINT || "Your search endpoint";
const searchIndex = process.env.AZURE_AI_SEARCH_INDEX || "Your search index";

// keyless authentication    
const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

// Required Azure OpenAI deployment name and API version
const deploymentName = process.env.AZURE_OPENAI_DEPLOYMENT_NAME || "gpt-4";
const apiVersion = process.env.OPENAI_API_VERSION || "2024-07-01-preview";

function getClient(): AzureOpenAI {
  return new AzureOpenAI({
    endpoint,
    azureADTokenProvider,
    deployment: deploymentName,
    apiVersion,
  });
}

async function main() {
  const client = getClient();

  const messages = [
    { role: "user", content: "What are my available health plans?" },
  ];

  console.log(`Message: ${messages.map((m) => m.content).join("\n")}`);

  const events = await client.chat.completions.create({
    stream: true,
    messages: [
      {
        role: "user",
        content:
          "What's the most common feedback we received from our customers about the product?",
      },
    ],
    max_tokens: 128,
    model: "",
    data_sources: [
      {
        type: "azure_search",
        parameters: {
          endpoint: searchEndpoint,
          index_name: searchIndex,
          authentication: {
            type: "api_key",
            key: searchKey,
          },
        },
      },
    ],
  });

  let response = "";
  for await (const event of events) {
    for (const choice of event.choices) {
      const newText = choice.delta?.content;
      if (newText) {
        response += newText;
        // To see streaming results as they arrive, uncomment line below
        // console.log(newText);
      }
    }
  }
  console.log(response);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

  2. Creare il file per eseguire la tsconfig.json transpile del codice TypeScript e copiare il codice seguente per ECMAScript.

    {
    "compilerOptions": {
      "module": "NodeNext",
      "target": "ES2022", // Supports top-level await
      "moduleResolution": "NodeNext",
      "skipLibCheck": true, // Avoid type errors from node_modules
      "strict": true // Enable strict type-checking options
    },
    "include": ["*.ts"]
}

  3. Converti il codice da TypeScript a JavaScript.

    tsc

  4. Accedere ad Azure con il comando seguente:

    az login

  5. Eseguire il codice con il comando seguente:

    node index.js

Importante

Per la produzione, utilizzare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere questo articolo sulla sicurezza .

Risultato

Message: What are my available health plans?
The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans.

Prerequisiti

Riferimento | Codice sorgente | Pacchetto (pypi) | Esempi

Questi collegamenti fanno riferimento all'API OpenAI per Python. Non è disponibile OpenAI Python SDK specifico di Azure. Informazioni su come passare dai servizi OpenAI ad Azure OpenAI.

Aggiungere i dati usando il portale di Microsoft Foundry

Suggerimento

In alternativa, è possibile usare l'Azure Developer CLI per creare programmaticamente le risorse necessarie per Azure OpenAI sui tuoi dati.

Per aggiungere i dati usando il portale:

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia disattivato. Questi passaggi fanno riferimento a Foundry (versione classica).

  2. Selezionare la risorsa Azure OpenAI. Se si dispone di una risorsa Foundry, è possibile creare un progetto Foundry.

  3. Nel riquadro sinistro selezionare Playgrounds>Chat.

  4. Nel riquadro Installazione selezionare la distribuzione del modello.

  5. Selezionare Aggiungi dati>Aggiungi un'origine dati.

    Un'istantanea del playground della chat su Foundry.

  6. Nella pagina Origine dati :

    1. In Seleziona origine dati, seleziona Carica file (anteprima).

      Suggerimento

    2. La condivisione di risorse tra le origini (CORS) è necessaria per l'accesso all'account di archiviazione di Azure OpenAI. Se CORS non è già abilitato per la risorsa di Archiviazione BLOB di Azure, selezionare Attiva CORS.

    3. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure.

    4. Immettere un nome per il nuovo indice.

    5. Selezionare la casella di controllo che accetta gli effetti di fatturazione dell'uso di Azure AI Search.

    6. Seleziona Avanti.

    Un screenshot che mostra le opzioni per la selezione di un'origine dati nel portale Foundry.

  7. Nella pagina Carica file :

    1. Selezionare Sfoglia un file e quindi selezionare i propri dati o i dati di esempio scaricati dai prerequisiti.

    2. Selezionare Carica file.

    3. Seleziona Avanti.

  8. Nella pagina Gestione dati :

    1. Scegliere se abilitare la ricerca semantica o la ricerca vettoriale per l'indice.

      Importante

      • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. Per abilitare la ricerca semantica o vettoriale, la risorsa di Ricerca di intelligenza artificiale di Azure deve essere al livello Basic o superiore. Per altre informazioni, vedere Scegliere un livello e limiti del servizio.
      • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, Germania, cinese(Zh), giapponese, coreano, russo e arabo.

    2. Seleziona Avanti.

  9. Nella pagina Connessione dati :

    1. Scegliere se eseguire l'autenticazione usando un'identità gestita assegnata dal sistema o una chiave API.

    2. Seleziona Avanti.

  10. Esaminare le configurazioni e quindi selezionare Salva e chiudi.

    È ora possibile chattare con il modello, che usa i dati per costruire la risposta.

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI di Azure. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati usando il portale di Microsoft Foundry.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Un endpoint di esempio è https://my-resource.openai.azure.com.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Creare un ambiente Python

  1. Creare una nuova cartella denominata openai-python per il progetto e un nuovo file di codice Python denominato main.py. Passare a tale directory:
mkdir openai-python
cd openai-python
  1. Installare le librerie Python seguenti:
pip install openai
pip install python-dotenv

Creare l'app Python

  1. Dalla directory del progetto aprire il file main.py e aggiungere il codice seguente:
import os
import openai
import dotenv

dotenv.load_dotenv()

endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
api_key = os.environ.get("AZURE_OPENAI_API_KEY")
deployment = os.environ.get("AZURE_OPENAI_DEPLOYMENT_NAME")

client = openai.AzureOpenAI(
    azure_endpoint=endpoint,
    api_key=api_key,
    api_version="2024-10-21",
)

completion = client.chat.completions.create(
    model=deployment,
    messages=[
        {
            "role": "user",
            "content": "What are my available health plans?",
        },
    ],
    extra_body={
        "data_sources":[
            {
                "type": "azure_search",
                "parameters": {
                    "endpoint": os.environ["AZURE_AI_SEARCH_ENDPOINT"],
                    "index_name": os.environ["AZURE_AI_SEARCH_INDEX"],
                    "authentication": {
                        "type": "api_key",
                        "key": os.environ["AZURE_AI_SEARCH_API_KEY"],
                    }
                }
            }
        ],
    }
)

print(f"{completion.choices[0].message.role}: {completion.choices[0].message.content}")

Importante

Per la produzione, utilizzare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere questo articolo sulla sicurezza .

  1. Eseguire il comando seguente:
python main.py

L'applicazione stampa la risposta in un formato JSON adatto per l'uso in molti scenari. Include entrambe le risposte alla query e alle citazioni dai file caricati.

Prerequisiti

Aggiungere i dati usando il portale di Microsoft Foundry

Suggerimento

In alternativa, è possibile usare l'Azure Developer CLI per creare programmaticamente le risorse necessarie per Azure OpenAI sui tuoi dati.

Per aggiungere i dati usando il portale:

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia disattivato. Questi passaggi fanno riferimento a Foundry (versione classica).

  2. Selezionare la risorsa Azure OpenAI. Se si dispone di una risorsa Foundry, è possibile creare un progetto Foundry.

  3. Nel riquadro sinistro selezionare Playgrounds>Chat.

  4. Nel riquadro Installazione selezionare la distribuzione del modello.

  5. Selezionare Aggiungi dati>Aggiungi un'origine dati.

    Un'istantanea del playground della chat su Foundry.

  6. Nella pagina Origine dati :

    1. In Seleziona origine dati, seleziona Carica file (anteprima).

      Suggerimento

    2. La condivisione di risorse tra le origini (CORS) è necessaria per l'accesso all'account di archiviazione di Azure OpenAI. Se CORS non è già abilitato per la risorsa di Archiviazione BLOB di Azure, selezionare Attiva CORS.

    3. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure.

    4. Immettere un nome per il nuovo indice.

    5. Selezionare la casella di controllo che accetta gli effetti di fatturazione dell'uso di Azure AI Search.

    6. Seleziona Avanti.

    Un screenshot che mostra le opzioni per la selezione di un'origine dati nel portale Foundry.

  7. Nella pagina Carica file :

    1. Selezionare Sfoglia un file e quindi selezionare i propri dati o i dati di esempio scaricati dai prerequisiti.

    2. Selezionare Carica file.

    3. Seleziona Avanti.

  8. Nella pagina Gestione dati :

    1. Scegliere se abilitare la ricerca semantica o la ricerca vettoriale per l'indice.

      Importante

      • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. Per abilitare la ricerca semantica o vettoriale, la risorsa di Ricerca di intelligenza artificiale di Azure deve essere al livello Basic o superiore. Per altre informazioni, vedere Scegliere un livello e limiti del servizio.
      • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, Germania, cinese(Zh), giapponese, coreano, russo e arabo.

    2. Seleziona Avanti.

  9. Nella pagina Connessione dati :

    1. Scegliere se eseguire l'autenticazione usando un'identità gestita assegnata dal sistema o una chiave API.

    2. Seleziona Avanti.

  10. Esaminare le configurazioni e quindi selezionare Salva e chiudi.

    È ora possibile chattare con il modello, che usa i dati per costruire la risposta.

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI di Azure. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati usando il portale di Microsoft Foundry.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Un endpoint di esempio è https://my-resource.openai.azure.com.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Comandi di PowerShell di esempio

I modelli di chat OpenAI di Azure sono ottimizzati per lavorare con input formattati come conversazione. La variabile messages passa una matrice di dizionari con ruoli diversi nella conversazione delineata da sistema, utente, strumento e assistente. La variabile dataSources si connette all'indice di Ricerca cognitiva di Azure e consente ai modelli OpenAI di Azure di rispondere usando i dati.

Per ottenere una risposta da parte modello, è necessario terminare con un messaggio utente che indichi che è il turno della risposta dell'assistente.

Suggerimento

È possibile usare diversi parametri per modificare la risposta del modello, ad esempio temperature o top_p. Per altre informazioni, vedere la documentazione di riferimento.

# Azure OpenAI metadata variables
   $openai = @{
       api_key     = $Env:AZURE_OPENAI_API_KEY
       api_base    = $Env:AZURE_OPENAI_ENDPOINT # your endpoint should look like the following https://YOUR_RESOURCE_NAME.openai.azure.com/
       api_version = '2023-07-01-preview' # this may change in the future
       name        = 'YOUR-DEPLOYMENT-NAME-HERE' #This will correspond to the custom name you chose for your deployment when you deployed a model.
   }

   $acs = @{
       search_endpoint     = 'YOUR ACS ENDPOINT' # your endpoint should look like the following https://YOUR_RESOURCE_NAME.search.windows.net/
       search_key    = 'YOUR-ACS-KEY-HERE' # or use the Get-Secret cmdlet to retrieve the value
       search_index = 'YOUR-INDEX-NAME-HERE' # the name of your ACS index
   }

   # Completion text
   $body = @{
    dataSources = @(
        @{
            type = 'AzureCognitiveSearch'
            parameters = @{
                    endpoint = $acs.search_endpoint
                    key = $acs.search_key
                    indexName = $acs.search_index
                }
        }
    )
    messages = @(
            @{
                role = 'user'
                content = 'What are my available health plans?'
            }
    )
   } | convertto-json -depth 5

   # Header for authentication
   $headers = [ordered]@{
       'api-key' = $openai.api_key
   }

   # Send a completion call to generate an answer
   $url = "$($openai.api_base)/openai/deployments/$($openai.name)/extensions/chat/completions?api-version=$($openai.api_version)"

   $response = Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Post -ContentType 'application/json'
   return $response.choices.messages[1].content

Output di esempio

The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans.

Importante

Per la produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio La gestione dei segreti di PowerShell con Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere questo articolo sulla sicurezza .

Chattare con il modello usando un'app Web

Per iniziare a chattare con il modello OpenAI di Azure che usa i dati, è possibile distribuire un'app Web usando il portale di Microsoft Foundry o il codice di esempio fornito in GitHub. Questa app viene distribuita usando il servizio app di Azure e fornisce un'interfaccia utente per l'invio di query. Questa app può essere usata con modelli OpenAI di Azure che usano i dati o modelli che non li usano. Per istruzioni sui requisiti, la configurazione e la distribuzione, vedere il file readme nel repository. Facoltativamente, è possibile personalizzare la logica front-end e back-end dell'app Web apportando modifiche al codice sorgente.

Prerequisiti

Riferimento | Codice sorgente | Pacchetto (Go) | Esempi

Aggiungere i dati usando il portale di Microsoft Foundry

Suggerimento

In alternativa, è possibile usare l'Azure Developer CLI per creare programmaticamente le risorse necessarie per Azure OpenAI sui tuoi dati.

Per aggiungere i dati usando il portale:

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia disattivato. Questi passaggi fanno riferimento a Foundry (versione classica).

  2. Selezionare la risorsa Azure OpenAI. Se si dispone di una risorsa Foundry, è possibile creare un progetto Foundry.

  3. Nel riquadro sinistro selezionare Playgrounds>Chat.

  4. Nel riquadro Installazione selezionare la distribuzione del modello.

  5. Selezionare Aggiungi dati>Aggiungi un'origine dati.

    Un'istantanea del playground della chat su Foundry.

  6. Nella pagina Origine dati :

    1. In Seleziona origine dati, seleziona Carica file (anteprima).

      Suggerimento

    2. La condivisione di risorse tra le origini (CORS) è necessaria per l'accesso all'account di archiviazione di Azure OpenAI. Se CORS non è già abilitato per la risorsa di Archiviazione BLOB di Azure, selezionare Attiva CORS.

    3. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure.

    4. Immettere un nome per il nuovo indice.

    5. Selezionare la casella di controllo che accetta gli effetti di fatturazione dell'uso di Azure AI Search.

    6. Seleziona Avanti.

    Un screenshot che mostra le opzioni per la selezione di un'origine dati nel portale Foundry.

  7. Nella pagina Carica file :

    1. Selezionare Sfoglia un file e quindi selezionare i propri dati o i dati di esempio scaricati dai prerequisiti.

    2. Selezionare Carica file.

    3. Seleziona Avanti.

  8. Nella pagina Gestione dati :

    1. Scegliere se abilitare la ricerca semantica o la ricerca vettoriale per l'indice.

      Importante

      • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. Per abilitare la ricerca semantica o vettoriale, la risorsa di Ricerca di intelligenza artificiale di Azure deve essere al livello Basic o superiore. Per altre informazioni, vedere Scegliere un livello e limiti del servizio.
      • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, Germania, cinese(Zh), giapponese, coreano, russo e arabo.

    2. Seleziona Avanti.

  9. Nella pagina Connessione dati :

    1. Scegliere se eseguire l'autenticazione usando un'identità gestita assegnata dal sistema o una chiave API.

    2. Seleziona Avanti.

  10. Esaminare le configurazioni e quindi selezionare Salva e chiudi.

    È ora possibile chattare con il modello, che usa i dati per costruire la risposta.

Prerequisiti di Microsoft Entra ID

Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, è necessario:

  • Installare l'Azure CLI utilizzata per l'autenticazione senza password con Microsoft Entra ID.
  • Assegna il ruolo Cognitive Services User al tuo account utente. È possibile assegnare ruoli nel portale di Azure in Controllo di accesso (IAM)>Aggiungere un'assegnazione di ruolo.

Configurazione

  1. Creare una nuova cartella dall-e-quickstart e passare alla cartella quickstart con il comando seguente:

     mkdir dall-e-quickstart && cd dall-e-quickstart

  2. Per l'autenticazione senza chiave consigliata con Microsoft Entra ID, accedere ad Azure con il comando seguente:

     az login

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI di Azure. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati usando il portale di Microsoft Foundry.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Un endpoint di esempio è https://my-resource.openai.azure.com.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Eseguire l'avvio rapido

Il codice di esempio in questa guida introduttiva usa l'ID Microsoft Entra per l'autenticazione senza chiave consigliata. Se si preferisce usare una chiave API, è possibile sostituire l'implementazione NewDefaultAzureCredential con NewKeyCredential.

azureOpenAIEndpoint := os.Getenv("AZURE_OPENAI_ENDPOINT")
credential, err := azidentity.NewDefaultAzureCredential(nil)
client, err := azopenai.NewClient(azureOpenAIEndpoint, credential, nil)

Per eseguire l'esempio:

  1. Creare un nuovo file denominato quickstart.go. Copiare il codice seguente nel file quickstart.go .

    package main

import (
 "context"
 "fmt"
 "log"
 "os"

 "github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
 "github.com/Azure/azure-sdk-for-go/sdk/azcore"
 "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)

func main() {
 azureOpenAIEndpoint := os.Getenv("AZURE_OPENAI_ENDPOINT")
 credential, err := azidentity.NewDefaultAzureCredential(nil)
 client, err := azopenai.NewClient(azureOpenAIEndpoint, credential, nil)

 modelDeploymentID := os.Getenv("AZURE_OPENAI_DEPLOYMENT_NAME")

 // Azure AI Search configuration
 searchIndex := os.Getenv("AZURE_AI_SEARCH_INDEX")
 searchEndpoint := os.Getenv("AZURE_AI_SEARCH_ENDPOINT")
 searchAPIKey := os.Getenv("AZURE_AI_SEARCH_API_KEY")

 if modelDeploymentID == "" || azureOpenAIEndpoint == "" || searchIndex == "" || searchEndpoint == "" || searchAPIKey == "" {
 	fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
 	return
 }

 client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, credential, nil)

 if err != nil {
 	// Implement application specific error handling logic.
 	log.Printf("ERROR: %s", err)
 	return
 }

 resp, err := client.GetChatCompletions(context.TODO(), azopenai.ChatCompletionsOptions{
 	Messages: []azopenai.ChatRequestMessageClassification{
 		&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("What are my available health plans?")},
 	},
 	MaxTokens: to.Ptr[int32](512),
 	AzureExtensionsOptions: []azopenai.AzureChatExtensionConfigurationClassification{
 		&azopenai.AzureSearchChatExtensionConfiguration{
 			// This allows Azure OpenAI to use an Azure AI Search index.
 			// Answers are based on the model's pretrained knowledge
 			// and the latest information available in the designated data source. 
 			Parameters: &azopenai.AzureSearchChatExtensionParameters{
 				Endpoint:  &searchEndpoint,
 				IndexName: &searchIndex,
 				Authentication: &azopenai.OnYourDataAPIKeyAuthenticationOptions{
 					Key: &searchAPIKey,
 				},
 			},
 		},
 	},
 	DeploymentName: &modelDeploymentID,
 }, nil)

 if err != nil {
 	// Implement application specific error handling logic.
 	log.Printf("ERROR: %s", err)
 	return
 }

 fmt.Fprintf(os.Stderr, "Extensions Context Role: %s\nExtensions Context (length): %d\n",
 	*resp.Choices[0].Message.Role,
 	len(*resp.Choices[0].Message.Content))

 fmt.Fprintf(os.Stderr, "ChatRole: %s\nChat content: %s\n",
 	*resp.Choices[0].Message.Role,
 	*resp.Choices[0].Message.Content,
 )
}

  2. Eseguire il comando seguente per creare un nuovo modulo Go:

     go mod init quickstart.go

  3. Eseguire go mod tidy per installare le dipendenze necessarie:

     go mod tidy

  4. Eseguire il comando seguente per eseguire l'esempio:

     go run quickstart.go

L'applicazione stampa la risposta, incluse entrambe le risposte alla query e alle citazioni dei file caricati.

Prerequisiti

Aggiungere i dati usando il portale di Microsoft Foundry

Suggerimento

In alternativa, è possibile usare l'Azure Developer CLI per creare programmaticamente le risorse necessarie per Azure OpenAI sui tuoi dati.

Per aggiungere i dati usando il portale:

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia disattivato. Questi passaggi fanno riferimento a Foundry (versione classica).

  2. Selezionare la risorsa Azure OpenAI. Se si dispone di una risorsa Foundry, è possibile creare un progetto Foundry.

  3. Nel riquadro sinistro selezionare Playgrounds>Chat.

  4. Nel riquadro Installazione selezionare la distribuzione del modello.

  5. Selezionare Aggiungi dati>Aggiungi un'origine dati.

    Un'istantanea del playground della chat su Foundry.

  6. Nella pagina Origine dati :

    1. In Seleziona origine dati, seleziona Carica file (anteprima).

      Suggerimento

    2. La condivisione di risorse tra le origini (CORS) è necessaria per l'accesso all'account di archiviazione di Azure OpenAI. Se CORS non è già abilitato per la risorsa di Archiviazione BLOB di Azure, selezionare Attiva CORS.

    3. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure.

    4. Immettere un nome per il nuovo indice.

    5. Selezionare la casella di controllo che accetta gli effetti di fatturazione dell'uso di Azure AI Search.

    6. Seleziona Avanti.

    Un screenshot che mostra le opzioni per la selezione di un'origine dati nel portale Foundry.

  7. Nella pagina Carica file :

    1. Selezionare Sfoglia un file e quindi selezionare i propri dati o i dati di esempio scaricati dai prerequisiti.

    2. Selezionare Carica file.

    3. Seleziona Avanti.

  8. Nella pagina Gestione dati :

    1. Scegliere se abilitare la ricerca semantica o la ricerca vettoriale per l'indice.

      Importante

      • La ricerca semantica e la ricerca vettoriale sono soggetti a prezzi aggiuntivi. Per abilitare la ricerca semantica o vettoriale, la risorsa di Ricerca di intelligenza artificiale di Azure deve essere al livello Basic o superiore. Per altre informazioni, vedere Scegliere un livello e limiti del servizio.
      • Per migliorare la qualità della risposta al recupero e al modello delle informazioni, è consigliabile abilitare la ricerca semantica per le seguenti lingue di origine dati: inglese, francese, spagnolo, portoghese, italiano, Germania, cinese(Zh), giapponese, coreano, russo e arabo.

    2. Seleziona Avanti.

  9. Nella pagina Connessione dati :

    1. Scegliere se eseguire l'autenticazione usando un'identità gestita assegnata dal sistema o una chiave API.

    2. Seleziona Avanti.

  10. Esaminare le configurazioni e quindi selezionare Salva e chiudi.

    È ora possibile chattare con il modello, che usa i dati per costruire la risposta.

Recuperare le informazioni sulle risorse

È necessario recuperare le informazioni seguenti per autenticare l'applicazione con la risorsa OpenAI di Azure. Questa guida introduttiva presuppone che i dati siano stati caricati in un account di archiviazione BLOB di Azure e che sia stato creato un indice di Azure AI Search. Vedere Aggiungere i dati usando il portale di Microsoft Foundry.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed Endpoint durante l'esame della risorsa di Azure OpenAI dal portale di Azure. Un endpoint di esempio è https://my-resource.openai.azure.com.
AZURE_OPENAI_DEPLOYMENT_NAME Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Gestione risorse>Distribuzioni nel portale di Azure.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica durante l'esame della risorsa di Azure AI Search dal portale di Azure.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. Può essere trovato nella sezione Panoramica quando si esamina la risorsa Azure AI Search dal portale di Azure.

Altre informazioni sull'autenticazione senza chiave e sull'impostazione delle variabili di ambiente.

Comandi cURL di esempio

I modelli di chat OpenAI di Azure sono ottimizzati per lavorare con input formattati come conversazione. La variabile messages passa una matrice di dizionari con ruoli diversi nella conversazione delineata da sistema, utente, strumento e assistente. La variabile dataSources si connette all'indice di Azure AI Search e consente ai modelli OpenAI di Azure di rispondere usando i dati.

Per ottenere una risposta da parte modello, è necessario terminare con un messaggio utente che indichi che è il turno della risposta dell'assistente.

Suggerimento

È possibile usare diversi parametri per modificare la risposta del modello, ad esempio temperature o top_p. Per altre informazioni, vedere la documentazione di riferimento.

curl -i -X POST $AZURE_OPENAI_ENDPOINT/openai/deployments/$AZURE_OPENAI_DEPLOYMENT_NAME/chat/completions?api-version=2024-10-21 \
-H "Content-Type: application/json" \
-H "api-key: $AZURE_OPENAI_API_KEY" \
-d \
'
{
    "data_sources": [
        {
            "type": "azure_search",
            "parameters": {
                "endpoint": "'$AZURE_AI_SEARCH_ENDPOINT'",
                "index_name": "'$AZURE_AI_SEARCH_INDEX'",
                "authentication": {
                    "type": "api_key",
                    "key": "'$AZURE_AI_SEARCH_API_KEY'"
                }
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are my available health plans?"
        }
    ]
}
'

Output di esempio

{
    "id": "12345678-1a2b-3c4e5f-a123-12345678abcd",
    "model": "gpt-4",
    "created": 1709835345,
    "object": "extensions.chat.completion",
    "choices": [
        {
            "index": 0,
            "finish_reason": "stop",
            "message": {
                "role": "assistant",
                "content": "The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans. [doc1].",
                "end_turn": true,
                "context": {
                    "citations": [
                        {
                            "content": "...",
                            "title": "...",
                            "url": "https://mysearch.blob.core.windows.net/xyz/001.txt",
                            "filepath": "001.txt",
                            "chunk_id": "0"
                        }
                    ],
                    "intent": "[\"Available health plans\"]"
                }
            }
        }
    ],
    "usage": {
        "prompt_tokens": 3779,
        "completion_tokens": 105,
        "total_tokens": 3884
    },
    "system_fingerprint": "fp_65792305e4"
}

Chattare con il modello usando un'app Web

Per iniziare a chattare con il modello OpenAI di Azure che usa i dati, è possibile distribuire un'app Web usando il portale di Microsoft Foundry o il codice di esempio fornito in GitHub. Questa app viene distribuita usando il servizio app di Azure e fornisce un'interfaccia utente per l'invio di query. Questa app può essere usata con modelli OpenAI di Azure che usano i dati o modelli che non li usano. Per istruzioni sui requisiti, la configurazione e la distribuzione, vedere il file readme nel repository. Facoltativamente, è possibile personalizzare la logica front-end e back-end dell'app Web apportando modifiche al codice sorgente.

Pulire le risorse

Se si vuole ripulire e rimuovere una risorsa Azure OpenAI o Azure AI Search, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse elimina anche tutte le altre risorse associate.

Passaggi successivi

  • Last updated on