Share via

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

  • Articolo

Esempio di codice sorgente del codice | | sorgente

Esempi del pacchetto del codice | sorgente di riferimento | (npm) |

Esempi del pacchetto del codice | sorgente di riferimento | (pypi) |

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

Esempi del pacchetto del codice | sorgente di riferimento | (Go) |

In questa guida introduttiva è possibile usare i propri dati con i modelli OpenAI di Azure. L'uso dei modelli di OpenAI di Azure sui dati può offrire una potente piattaforma di intelligenza artificiale conversazionale che consente comunicazioni più veloci e accurate.

Prerequisiti

  • Una sottoscrizione di Azure: crearne una gratuitamente.

  • Accesso concesso ad Azure OpenAI nella sottoscrizione di Azure desiderata.

    Azure OpenAI richiede la registrazione ed è attualmente disponibile solo per i clienti e i partner aziendali approvati. Per altre informazioni, vedere Accesso limitato al servizio OpenAI di Azure. È possibile richiedere l'accesso a OpenAI di Azure completando il modulo all'indirizzo https://aka.ms/oai/access. Apri un problema in questo repository per contattare Microsoft in caso di problemi.

  • Una risorsa OpenAI di Azure distribuita in un'area supportata con un modello supportato.

  • Assicurarsi di aver assegnato almeno il ruolo Collaboratore servizi cognitivi per la risorsa OpenAI di Azure.

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

Si è verificato un problema con i prerequisiti.

Aggiungere i dati con Azure OpenAI Studio

Suggerimento

È possibile usare l'interfaccia della riga di comando per sviluppatori di Azure per creare a livello di codice le risorse necessarie per Azure OpenAI nei dati

Passare ad Azure OpenAI Studio e accedere con le credenziali che hanno accesso alla risorsa OpenAI di Azure. Durante o dopo il flusso di lavoro di accesso, selezionare la directory appropriata, la sottoscrizione di Azure e la risorsa OpenAI di Azure.

  1. Selezionare il riquadro Bring your own data (Bring your own data )

    Screenshot della pagina di destinazione di Azure OpenAI Studio.

  2. Nel riquadro visualizzato selezionare Carica file (anteprima) in Seleziona origine dati. Azure OpenAI richiede sia una risorsa di archiviazione che una risorsa di ricerca per accedere e indicizzare i dati.

    Suggerimento

    1. Per consentire ad Azure OpenAI di accedere all'account di archiviazione, è necessario attivare la condivisione di risorse tra le origini (CORS). Se CORS non è già attivato per la risorsa Archiviazione BLOB di Azure, selezionare Attiva CORS.

    2. Selezionare la risorsa di Ricerca intelligenza artificiale di Azure e selezionare il riconoscimento che la connessione comporta l'utilizzo nell'account. Fare quindi clic su Avanti.

    Screenshot che mostra le opzioni per la selezione di un'origine dati in Azure OpenAI Studio.

  3. Nel riquadro Carica file selezionare Cerca un file e selezionare i file scaricati dalla sezione prerequisiti o i propri dati. Selezionare quindi Carica file. Fare quindi clic su Avanti.

  4. Nel riquadro Gestione dati è possibile scegliere se abilitare la ricerca semantica o vettoriale per l'indice.

    Importante

    • La ricerca semantica e la ricerca vettoriale sono soggette a prezzi aggiuntivi. È necessario scegliere SKU Basic o superiore per abilitare la ricerca semantica o la ricerca vettoriale. Per altre informazioni, vedere Differenze del piano tariffario 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.

  5. Esaminare i dettagli immessi e selezionare Salva e chiudi. È ora possibile chattare con il modello e usare le informazioni dai dati per costruire la risposta.

Si è verificato un problema durante l'aggiunta dei dati.

Playground Chat

Iniziare a esplorare le funzionalità di Azure OpenAI con un approccio senza codice tramite il playground della 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 di Azure OpenAI Studio con le sezioni evidenziate.

Il playground offre opzioni per personalizzare l'esperienza di chat. A destra, è possibile selezionare Distribuzione 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 delle conversazioni fornisce il contesto per generare risposte correlate, ma usa anche l'utilizzo dei token. L'indicatore di stato del token di input tiene traccia del numero di token della domanda che si invia.

Le impostazioni avanzate a sinistra sono parametri di runtime, che consentono di controllare il recupero e la ricerca di informazioni pertinenti dai dati. Un caso d'uso valido è quando si vuole assicurarsi che le risposte vengano generate solo in base ai dati o che il modello non possa generare una risposta in base alle informazioni esistenti sui dati.

  • La rigidità determina l'aggressività del sistema nell'applicazione di filtri ai documenti di ricerca in base ai punteggi di somiglianza. L'impostazione della rigidità 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 svolgono 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 recuperati sono un numero intero che può essere impostato su 3, 5, 10 o 20 e controlla il numero di blocchi di documenti forniti al modello linguistico di grandi dimensioni per simulare la risposta finale. Per impostazione predefinita, questa opzione è impostata su 5.

  • Quando è abilitato Limitare le risposte ai dati , 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 miei piani sanitari 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 è 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 di Azure OpenAI Studio). Come si può immaginare, porre una domanda su "tutti i titoli" richiede un'analisi completa dell'intero archivio vettoriale.

Distribuire il modello

Dopo aver soddisfatto l'esperienza in Azure OpenAI Studio, è possibile distribuire un'app Web direttamente da Studio selezionando il pulsante Distribuisci in .

Screenshot che mostra il pulsante di distribuzione del modello in Azure OpenAI Studio.

In questo modo è possibile eseguire la distribuzione in un'applicazione Web autonoma o un copilota in Copilot Studio (anteprima) se si usano dati personalizzati 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 dell'URL dell'app. 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.

Si è verificato un problema con la distribuzione del modello.

Recuperare le variabili obbligatorie

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessarie le variabili seguenti. 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 Ricerca intelligenza artificiale di Azure. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa OpenAI di Azure dal portale di Azure. In alternativa, è possibile trovare il valore nella visualizzazione Codice del playground>chat di Azure AI Studio>. Un endpoint di esempio è: https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Chiavi e endpoint di gestione>delle risorse quando si esamina la risorsa OpenAI di Azure dalla portale di Azure. Puoi usare entrambi KEY1 o KEY2. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Distribuzioni di Gestione>risorse nel portale di Azure o in alternativa in Distribuzioni di gestione>in Azure AI Studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni> Keys quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure. È possibile usare la chiave di amministrazione primaria o la chiave di amministrazione secondaria. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. È possibile trovarla nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.

Variabili di ambiente

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema con la configurazione.

Creare una nuova applicazione .NET Core

In una finestra di una console, ad esempio cmd, PowerShell o Bash, usare il comando dotnet new per creare una nuova app console con il nome azure-openai-quickstart. Questo comando crea un semplice progetto "Hello World" con un singolo file di origine C#: Program.cs.

dotnet new console -n azure-openai-quickstart

Spostarsi nella cartella dell'app appena creata. È possibile compilare l'applicazione con il comando seguente:

dotnet build

L'output di compilazione non deve contenere alcun avviso o errore.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Installare la libreria client .NET OpenAI con:

dotnet add package Azure.AI.OpenAI --prerelease

Dalla directory del progetto aprire il file Program.cs e sostituirlo con il codice seguente:

Senza flusso di risposta

using Azure;
using Azure.AI.OpenAI;
using System.Text.Json;
using static System.Environment;

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


var client = new OpenAIClient(new Uri(azureOpenAIEndpoint), new AzureKeyCredential(azureOpenAIKey));

var chatCompletionsOptions = new ChatCompletionsOptions()
{
    Messages =
    {
        new ChatRequestUserMessage("What are my available health plans?"),
    },
    AzureExtensionsOptions = new AzureChatExtensionsOptions()
    {
        Extensions =
        {
            new AzureCognitiveSearchChatExtensionConfiguration()
            {
                SearchEndpoint = new Uri(searchEndpoint),
                Key = searchKey,
                IndexName = searchIndex,
            },
        }
    },
    DeploymentName = deploymentName
};

Response<ChatCompletions> response = client.GetChatCompletions(chatCompletionsOptions);

ChatResponseMessage responseMessage = response.Value.Choices[0].Message;

Console.WriteLine($"Message from {responseMessage.Role}:");
Console.WriteLine("===");
Console.WriteLine(responseMessage.Content);
Console.WriteLine("===");

Console.WriteLine($"Context information (e.g. citations) from chat extensions:");
Console.WriteLine("===");
foreach (ChatResponseMessage contextMessage in responseMessage.AzureExtensionsContext.Messages)
{
    string contextContent = contextMessage.Content;
    try
    {
        var contextMessageJson = JsonDocument.Parse(contextMessage.Content);
        contextContent = JsonSerializer.Serialize(contextMessageJson, new JsonSerializerOptions()
        {
            WriteIndented = true,
        });
    }
    catch (JsonException)
    {}
    Console.WriteLine($"{contextMessage.Role}: {contextContent}");
}
Console.WriteLine("===");

Importante

Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sicurezza dei servizi di intelligenza artificiale di Azure.

dotnet run program.cs

Output

Answer from assistant:
===
The available health plans in the Contoso Electronics plan and benefit packages are the Northwind Health Plus and Northwind Standard plans [^1^].
===
Context information (e.g. citations) from chat extensions:
===
tool: {
  "citations": [
    {
      "content": "...",
      "id": null,
      "title": "...",
      "filepath": "...",
      "url": "...",
      "metadata": {
        "chunking": "orignal document size=1011. Scores=3.6390076 and None.Org Highlight count=38."
      },
      "chunk_id": "2"
    },
    ...
  ],
  "intent": "[\u0022What are my available health plans?\u0022]"
}
===

Questa operazione attenderà fino a quando il modello non ha generato l'intera risposta prima di stampare i risultati. In alternativa, se si desidera trasmettere in modo asincrono la risposta e stampare i risultati, è possibile sostituire il contenuto di Program.cs con il codice nell'esempio successivo.

Asincrona con streaming

using Azure;
using Azure.AI.OpenAI;
using System.Text.Json;
using static System.Environment;

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


var client = new OpenAIClient(new Uri(azureOpenAIEndpoint), new AzureKeyCredential(azureOpenAIKey));

var chatCompletionsOptions = new ChatCompletionsOptions()
{
    DeploymentName = deploymentName,
    Messages =
    {
        new ChatRequestUserMessage("What are my available health plans?"),
    },
    AzureExtensionsOptions = new AzureChatExtensionsOptions()
    {
        Extensions =
        {
            new AzureCognitiveSearchChatExtensionConfiguration()
            {
                SearchEndpoint = new Uri(searchEndpoint),
                Key = searchKey,
                IndexName = searchIndex,
            },
        }
    }
};
await foreach (StreamingChatCompletionsUpdate chatUpdate in client.GetChatCompletionsStreaming(chatCompletionsOptions))
{
    if (chatUpdate.Role.HasValue)
    {
        Console.Write($"{chatUpdate.Role.Value.ToString().ToUpperInvariant()}: ");
    }
    if (!string.IsNullOrEmpty(chatUpdate.ContentUpdate))
    {
        Console.Write(chatUpdate.ContentUpdate);
    }
}

Si è verificato un problema durante l'esecuzione degli esempi di codice.

Recuperare le variabili obbligatorie

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessarie le variabili seguenti. 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 Ricerca intelligenza artificiale di Azure. Per altre informazioni, vedere Aggiungere i dati con Azure AI Studio.

Nome variabile Valore
AZURE_OPENAI_ENDPOINT È possibile trovare questo valore nella sezione Chiavi ed endpoint quando si esamina la risorsa OpenAI di Azure dal portale di Azure. In alternativa, è possibile trovare il valore nella visualizzazione Codice del playground>chat di Azure AI Studio>. Un endpoint di esempio è: https://my-resource.openai.azure.com.
AZURE_OPENAI_API_KEY È possibile trovare questo valore nella sezione Chiavi e endpoint di gestione>delle risorse quando si esamina la risorsa OpenAI di Azure dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro 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 in Distribuzioni di Gestione>risorse nella portale di Azure o in alternativa in Distribuzioni di gestione>in Azure AI Studio.
AZURE_AI_SEARCH_ENDPOINT È possibile trovare questo valore nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure.
AZURE_AI_SEARCH_API_KEY È possibile trovare questo valore nella sezione Impostazioni> Keys quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure. È possibile usare la chiave di amministrazione primaria o la chiave di amministrazione secondaria. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. È possibile trovarla nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.

Variabili di ambiente

Nota

Spring AI imposta per impostazione predefinita il nome del modello su gpt-35-turbo. È necessario specificare il SPRING_AI_AZURE_OPENAI_MODEL valore 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

Si è verificato un problema con la configurazione.

Creare una nuova applicazione Spring

Spring AI non supporta attualmente le AzureCognitiveSearchChatExtensionConfiguration opzioni che consentono a una query di Intelligenza artificiale di Azure di incapsulare il metodo Retrieval Augmented Generation (RAG) e 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

Eseguire il comando spring init dalla 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 di 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 AI service. 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 l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sicurezza dei servizi di intelligenza artificiale di Azure.

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

    ./mvnw spring-boot:run

Output

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: 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 AI service. 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.

Si è verificato un problema durante l'esecuzione degli esempi di codice.

Recuperare le variabili obbligatorie

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessarie le variabili seguenti. 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 Ricerca intelligenza artificiale di Azure. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa OpenAI di Azure dal portale di Azure. In alternativa, è possibile trovare il valore nella visualizzazione Codice del playground>chat di Azure AI Studio>. Un endpoint di esempio è: https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Chiavi e endpoint di gestione>delle risorse quando si esamina la risorsa OpenAI di Azure dalla portale di Azure. Puoi usare entrambi KEY1 o KEY2. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Distribuzioni di Gestione>risorse nel portale di Azure o in alternativa in Distribuzioni di gestione>in Azure AI Studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni> Keys quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure. È possibile usare la chiave di amministrazione primaria o la chiave di amministrazione secondaria. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. È possibile trovarla nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.

Variabili di ambiente

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema con la configurazione.

Creare un'applicazione Node

In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app. Eseguire quindi il npm init comando per creare un'applicazione node con un file package.json .

npm init

Installare la libreria client

Installare il client OpenAI di Azure e le librerie di identità di Azure per JavaScript con npm:

npm install @azure/openai @azure/identity

Il file di package.json dell'app verrà aggiornato con le dipendenze.

Creare un'applicazione di esempio

Aprire un prompt dei comandi in cui si vuole il nuovo progetto e creare un nuovo file denominato ChatWithOwnData.js. Copiare il codice seguente nel file ChatWithOwnData.js.

const { OpenAIClient, AzureKeyCredential } = require("@azure/openai");

// Set the Azure and AI Search values from environment variables
const endpoint = process.env["AZURE_OPENAI_ENDPOINT"];
const azureApiKey = process.env["AZURE_OPENAI_API_KEY"];
const deploymentId = process.env["AZURE_OPENAI_DEPLOYMENT_ID"];
const searchEndpoint = process.env["AZURE_AI_SEARCH_ENDPOINT"];
const searchKey = process.env["AZURE_AI_SEARCH_API_KEY"];
const searchIndex = process.env["AZURE_AI_SEARCH_INDEX"];


async function main(){
  const client = new OpenAIClient(endpoint, new AzureKeyCredential(azureApiKey));

  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.streamChatCompletions(deploymentId, messages, { 
    maxTokens: 128,
    azureExtensionOptions: {
      extensions: [
        {
          type: "AzureCognitiveSearch",
          endpoint: searchEndpoint,
          key: searchKey,
          indexName: searchIndex,
        },
      ],
    },
  });
  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);
});



module.exports = { main };

Importante

Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sicurezza dei servizi di intelligenza artificiale di Azure.

node.exe ChatWithOwnData.js

Output

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.

Si è verificato un problema durante l'esecuzione dell'esempio di codice.

Recuperare le variabili obbligatorie

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessarie le variabili seguenti. 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 Ricerca intelligenza artificiale di Azure. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa OpenAI di Azure dal portale di Azure. In alternativa, è possibile trovare il valore nella visualizzazione Codice del playground>chat di Azure AI Studio>. Un endpoint di esempio è: https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Chiavi e endpoint di gestione>delle risorse quando si esamina la risorsa OpenAI di Azure dalla portale di Azure. Puoi usare entrambi KEY1 o KEY2. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Distribuzioni di Gestione>risorse nel portale di Azure o in alternativa in Distribuzioni di gestione>in Azure AI Studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni> Keys quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure. È possibile usare la chiave di amministrazione primaria o la chiave di amministrazione secondaria. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. È possibile trovarla nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.

Variabili di ambiente

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema con la configurazione.

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_ID")

client = openai.AzureOpenAI(
    azure_endpoint=endpoint,
    api_key=api_key,
    api_version="2024-02-01",
)

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(completion.model_dump_json(indent=2))

Importante

Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sicurezza dei servizi di intelligenza artificiale di Azure.

  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.

Si è verificato un problema durante l'esecuzione degli esempi di codice.

Recuperare le variabili obbligatorie

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessarie le variabili seguenti. 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 Ricerca intelligenza artificiale di Azure. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa OpenAI di Azure dal portale di Azure. In alternativa, è possibile trovare il valore nella visualizzazione Codice del playground>chat di Azure AI Studio>. Un endpoint di esempio è: https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Chiavi e endpoint di gestione>delle risorse quando si esamina la risorsa OpenAI di Azure dalla portale di Azure. Puoi usare entrambi KEY1 o KEY2. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Distribuzioni di Gestione>risorse nel portale di Azure o in alternativa in Distribuzioni di gestione>in Azure AI Studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni> Keys quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure. È possibile usare la chiave di amministrazione primaria o la chiave di amministrazione secondaria. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. È possibile trovarla nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.

Variabili di ambiente

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema con la configurazione.

Comandi di PowerShell di esempio

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

Per attivare una risposta dal modello, è necessario terminare con un messaggio utente che indica che è il turno dell'assistente per rispondere.

Suggerimento

Esistono diversi parametri che è possibile usare 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 l'articolo sicurezza dei servizi di intelligenza artificiale di Azure.

Si è verificato un problema con l'invio della richiesta.

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 Azure OpenAI Studio 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 usano i dati. Per istruzioni sui requisiti, la configurazione e la distribuzione, vedere il file leggimi nel repository. Facoltativamente, è possibile personalizzare la logica front-end e back-end dell'app Web apportando modifiche al codice sorgente.

Recuperare le variabili obbligatorie

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessarie le variabili seguenti. 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 Ricerca intelligenza artificiale di Azure. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa OpenAI di Azure dal portale di Azure. In alternativa, è possibile trovare il valore nella visualizzazione Codice del playground>chat di Azure AI Studio>. Un endpoint di esempio è: https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Chiavi e endpoint di gestione>delle risorse quando si esamina la risorsa OpenAI di Azure dalla portale di Azure. Puoi usare entrambi KEY1 o KEY2. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Distribuzioni di Gestione>risorse nel portale di Azure o in alternativa in Distribuzioni di gestione>in Azure AI Studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni> Keys quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure. È possibile usare la chiave di amministrazione primaria o la chiave di amministrazione secondaria. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. È possibile trovarla nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.

Variabili di ambiente

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema con la configurazione.

Creare un ambiente Go

  1. Creare una nuova cartella denominata openai-go per il progetto e un nuovo file di codice Go denominato sample.go. Passare a tale directory:

    mkdir openai-go
cd openai-go

  2. Installare i pacchetti Go seguenti:

    go get github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai

  3. Abilitare il rilevamento delle dipendenze per il codice.

    go mod init example/azure-openai

Creare l'app Go

  1. Dalla directory del progetto aprire il file sample.go e aggiungere il codice seguente:

    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() {
 azureOpenAIKey := os.Getenv("AZURE_OPENAI_API_KEY")
 modelDeploymentID := os.Getenv("AZURE_OPENAI_DEPLOYMENT_ID")

 // Ex: "https://<your-azure-openai-host>.openai.azure.com"
 azureOpenAIEndpoint := os.Getenv("AZURE_OPENAI_ENDPOINT")

 // 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 azureOpenAIKey == "" || modelDeploymentID == "" || azureOpenAIEndpoint == "" || searchIndex == "" || searchEndpoint == "" || searchAPIKey == "" {
 	fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
 	return
 }

 keyCredential := azcore.NewKeyCredential(azureOpenAIKey)

 // In Azure OpenAI you must deploy a model before you can use it in your client. For more information
 // see here: https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
 client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)

 if err != nil {
 	//  TODO: Update the following line with your application specific error handling logic
 	log.Fatalf("ERROR: %s", err)
 }

 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.AzureCognitiveSearchChatExtensionConfiguration{
 			// This allows Azure OpenAI to use an Azure AI Search index.
 			//
 			// > Because the model has access to, and can reference specific sources to support its responses, answers are not only based on its pretrained knowledge
 			// > but also on the latest information available in the designated data source. This grounding data also helps the model avoid generating responses
 			// > based on outdated or incorrect information.
 			//
 			// Quote from here: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/use-your-data
 			Parameters: &azopenai.AzureCognitiveSearchChatExtensionParameters{
 				Endpoint:  &searchEndpoint,
 				IndexName: &searchIndex,
 				Authentication: &azopenai.OnYourDataAPIKeyAuthenticationOptions{
 					Key: &searchAPIKey,
 				},
 			},
 		},
 	},
 	DeploymentName: &modelDeploymentID,
 }, nil)

 if err != nil {
 	//  TODO: Update the following line with your application specific error handling logic
 	log.Fatalf("ERROR: %s", err)
 }

 // Contains contextual information from your Azure chat completion extensions, configured above in `AzureExtensionsOptions`
 msgContext := resp.Choices[0].Message.Context

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

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

    Importante

    Per l'ambiente di produzione, usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sicurezza dei servizi di intelligenza artificiale di Azure.

  2. Eseguire il comando seguente:

    go run sample.go

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

Si è verificato un problema durante l'esecuzione degli esempi di codice.

Recuperare le variabili obbligatorie

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessarie le variabili seguenti. 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 Ricerca intelligenza artificiale di Azure. Vedere Aggiungere i dati con Azure AI Studio

Nome variabile Valore
AZURE_OPENAI_ENDPOINT Questo valore è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa OpenAI di Azure dal portale di Azure. In alternativa, è possibile trovare il valore nella visualizzazione Codice del playground>chat di Azure AI Studio>. Un endpoint di esempio è: https://my-resoruce.openai.azure.com.
AZURE_OPENAI_API_KEY Questo valore è disponibile nella sezione Chiavi e endpoint di gestione>delle risorse quando si esamina la risorsa OpenAI di Azure dalla portale di Azure. Puoi usare entrambi KEY1 o KEY2. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_OPENAI_DEPLOYMENT_ID Questo valore corrisponde al nome personalizzato scelto per la distribuzione quando è stato distribuito un modello. Questo valore è disponibile in Distribuzioni di Gestione>risorse nel portale di Azure o in alternativa in Distribuzioni di gestione>in Azure AI Studio.
AZURE_AI_SEARCH_ENDPOINT Questo valore è disponibile nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.
AZURE_AI_SEARCH_API_KEY Questo valore è disponibile nella sezione Impostazioni> Keys quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dal portale di Azure. È possibile usare la chiave di amministrazione primaria o la chiave di amministrazione secondaria. Avere sempre due chiavi consente di ruotare e rigenerare le chiavi in modo sicuro senza causare un'interruzione del servizio.
AZURE_AI_SEARCH_INDEX Questo valore corrisponde al nome dell'indice creato per archiviare i dati. È possibile trovarla nella sezione Panoramica quando si esamina la risorsa di Ricerca di intelligenza artificiale di Azure dall'portale di Azure.

Variabili di ambiente

setx AZURE_OPENAI_ENDPOINT REPLACE_WITH_YOUR_AOAI_ENDPOINT_VALUE_HERE

setx AZURE_OPENAI_API_KEY REPLACE_WITH_YOUR_AOAI_KEY_VALUE_HERE

setx AZURE_OPENAI_DEPLOYMENT_ID REPLACE_WITH_YOUR_AOAI_DEPLOYMENT_VALUE_HERE

setx AZURE_AI_SEARCH_ENDPOINT REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_VALUE_HERE

setx AZURE_AI_SEARCH_API_KEY REPLACE_WITH_YOUR_AZURE_SEARCH_RESOURCE_KEY_VALUE_HERE

setx AZURE_AI_SEARCH_INDEX REPLACE_WITH_YOUR_INDEX_NAME_HERE

Si è verificato un problema con la configurazione.

Comandi cURL di esempio

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

Per attivare una risposta dal modello, è necessario terminare con un messaggio utente che indica che è il turno dell'assistente per rispondere.

Suggerimento

Esistono diversi parametri che è possibile usare 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_ID/chat/completions?api-version=2024-02-15-preview \
-H "Content-Type: application/json" \
-H "api-key: $AZURE_OPENAI_API_KEY" \
-d \
'
{
    "data_sources": [
        {
            "type": "AzureCognitiveSearch",
            "parameters": {
                "endpoint": "'$AZURE_AI_SEARCH_ENDPOINT'",
                "key": "'$AZURE_AI_SEARCH_API_KEY'",
                "index_name": "'$AZURE_AI_SEARCH_INDEX'"
            }
        }
    ],
    "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
    }
}

Si è verificato un problema con l'invio della richiesta.

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 Azure OpenAI Studio 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 usano i dati. Per istruzioni sui requisiti, la configurazione e la distribuzione, vedere il file leggimi 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 pulire e rimuovere una risorsa di Ricerca di Azure OpenAI o azure per intelligenza artificiale, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

Passaggi successivi