Share via

Creare un'app di chat personalizzata in Python usando l'SDK del prompt flow

  • Articolo

Importante

Alcune funzionalità descritte in questo articolo potrebbero essere disponibili solo in anteprima. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Questo avvio rapido descrive la configurazione dell'ambiente di sviluppo locale con l'SDK del prompt flow. Si scrive un prompt, lo si esegue come parte del codice dell'app, si tracciano le chiamate LLM effettuate e si esegue una valutazione di base per gli output del LLM.

Prerequisiti

Prima di seguire questa guida introduttiva, creare le risorse necessarie per l'applicazione:

  • Hub di AI Studio per la connessione a risorse esterne.
  • Progetto per organizzare gli artefatti del progetto e condividere tracce e esecuzioni di valutazione.
  • Un modello di chat OpenAI di Azure distribuito (gpt-35-turbo o gpt-4)

Completare l'avvio rapido del playground di Studio AI per creare queste risorse, se non è già stato fatto. Per creare queste risorse è anche possibile seguire la Guida all'SDK per creare un hub e un progetto.

In aggiunta, è necessario disporre delle autorizzazioni necessarie per aggiungere le assegnazioni di ruolo per gli account di archiviazione nella sottoscrizione di Azure. La concessione delle autorizzazioni (con aggiunta dell'assegnazione di ruolo) è abilitata solo per il Proprietario delle specifiche risorse di Azure. Potrebbe essere necessario chiedere all'amministratore IT di fornire assistenza per concedere l'accesso alla chiamata al Servizio OpenAI di Azure usando la propria identità.

Concedere l'accesso per chiamare il Servizio OpenAI di Azure usando l'identità

Per usare le procedure consigliate per la sicurezza, anziché le chiavi API, si usa Microsoft Entra ID che consente di eseguire l'autenticazione con OpenAI di Azure usando l'identità utente.

L'utente/l’amministratore deve concedere all'identità utente il ruolo Utente OpenAI di Servizi cognitivi, sulla risorsa dei Servizi di Azure AI che si sta utilizzando. Questo ruolo concede la possibilità di chiamare il Servizio OpenAI di Azure usando l'identità utente.

Per concedere a se stessi l'accesso alla risorsa dei Servizi di Azure AI in uso:

  1. In Studio AI, passare al progetto e selezionare Impostazioni nel riquadro sinistro.

  2. Nella sezione Risorse connesse selezionare il nome della connessione con tipo AIServices.

    Screenshot della pagina delle impostazioni per il progetto, che evidenzia come selezionare, per aprirla, la risorsa dei Servizi IA connessa.

    Nota

    Se la connessione AIServices non viene visualizzata, al suo posto usare la connessione OpenAI di Azure.

  3. Nella pagina dei dettagli della risorsa, selezionare il collegamento nell'intestazione Risorsa per aprire la risorsa dei Servizi IA nel portale di Azure.

    Screenshot dei dettagli per la connessione ai Servizi IA che mostra come aprire la risorsa nel portale di Azure.

  4. Nella pagina sinistra del portale di Azure, selezionare Controllo di accesso (IAM)> e >Aggiungi assegnazione di ruolo.

  5. Cercare il ruolo Utente Servizi cognitivi OpenAI e selezionarlo. Quindi seleziona Avanti.

    Screenshot della pagina per selezionare il ruolo Utente Servizi cognitivi OpenAI.

  6. Selezionare Utente, gruppo o entità servizio. Quindi scegliere Seleziona membri.

  7. Si apre il riquadro Seleziona membri. Qui cercare il nome dell'utente per cui si vuole aggiungere l'assegnazione di ruolo. Selezionare l'utente, quindi Seleziona.

    Screenshot della pagina con l'utente a cui viene assegnato il nuovo ruolo.

  8. Continuare la procedura guidata e selezionare Rivedi e assegna per aggiungere l'assegnazione di ruolo.

Installare e accedere all'interfaccia della riga di comando di Azure

Ora si installa l'interfaccia della riga di comando di Azure e si accede dall'ambiente di sviluppo locale. Qui è possibile usare le credenziali utente per chiamare il servizio OpenAI di Azure.

Nella gran parte dei casi è possibile installare l'interfaccia della riga di comando di Azure dal terminale usando il comando seguente:

winget install -e --id Microsoft.AzureCLI

Se questi comandi non funzionano per il sistema operativo o l'installazione specifici, è possibile seguire le istruzioni in Come installare l'interfaccia della riga di comando di Azure.

Dopo aver installato l'interfaccia della riga di comando di Azure, accedere usando il comando az login e registrarsi usando il browser:

az login

A questo punto si crea l'app e si chiama il Servizio OpenAI di Azure, dal codice.

Creare un nuovo ambiente Python

Prima di tutto è necessario creare un nuovo ambiente Python per installare i pacchetti SDK del prompt flow. NON installare i pacchetti nell'installazione globale di Python. Quando si installano i pacchetti Python, è necessario usare sempre un ambiente virtuale o Conda, altrimenti si rischia di interrompere l'installazione di Python nel sistema.

Se necessario, installare Python

È consigliabile usare Python 3.10 o versione successiva; è comunque necessario avere almeno Python 3.8. Se non è installata una versione appropriata di Python, seguire le istruzioni riportate in Esercitazione di Vs Code Python, che descrive il modo più semplice per installare Python nel sistema operativo.

Creare un ambiente virtuale

Se Python 3.10 o versione successiva è già installato, è possibile creare un ambiente virtuale usando i comandi seguenti:

py -3 -m venv .venv
.venv\scripts\activate

L'attivazione dell'ambiente Python implica che quando si esegue python o pip dalla riga di comando, si userà l'interprete Python contenuto nella cartella .venv dell'applicazione.

Nota

Per uscire dall'ambiente virtuale Python è possibile usare il comando deactivate. Potrà poi essere riattivato successivamente, quando necessario.

Installare l'SDK del prompt flow

In questa sezione viene usato il prompt flow per compilare l'applicazione. [https://microsoft.github.io/promptflow/](Prompt flow) è una suite di strumenti di sviluppo progettati per semplificare il ciclo di sviluppo end-to-end delle applicazioni di IA basate su LLM, dall'ideazione, alla creazione di prototipi, ai test, alla valutazione per la distribuzione e il monitoraggio di produzione.

Usare pip per installare l'SDK del prompt flow nell'ambiente virtuale creato.

pip install promptflow
pip install azure-identity

L'SDK del prompt flow accetta una dipendenza da più pacchetti. È possibile scegliere di installarli separatamente se, per tutti, non si desiderano le opzioni seguenti:

  • promptflow-core: runtime del prompt flow di base usato per l'esecuzione del codice del LLM
  • promptflow-tracing: libreria leggera usata per la creazione delle tracce OpenTelemetry negli standard
  • promptflow-devkit: strumenti per il test del prompt flow e visualizzatore di traccia per gli ambienti di sviluppo locali
  • openai: librerie client per l'uso del servizio OpenAI di Azure
  • python-dotenv: uso per impostare le variabili di ambiente leggendole dai file .env

Configurare le variabili di ambiente

L'endpoint dei servizi di IA e il nome della distribuzione sono necessari per chiamare il servizio OpenAI di Azure dal codice. In questo avvio rapido, i valori sono salvati in un file .env, ossia un file che contiene variabili di ambiente che l'applicazione è in grado di leggere. Questi valori sono disponibili nel playground della chat di Studio AI.

  1. Creare un file .env e incollare il codice seguente:

    AZURE_OPENAI_ENDPOINT=endpoint_value
AZURE_OPENAI_DEPLOYMENT_NAME=deployment_name
AZURE_OPENAI_API_VERSION=2024-02-15-preview

  2. Passare al playground della chat all'interno del progetto di Studio AI. Prima di tutto inviare un messaggio all’LLM per verificare che la chat funzioni con il modello.

  3. Nel playground della chat trovare il nome della distribuzione di OpenAI di Azure. Selezionare la distribuzione nell'elenco a discesa e passare il puntatore del mouse sul nome della distribuzione, per visualizzarlo. In questo esempio il nome della distribuzione è gpt-35-turbo-16k.

    Screenshot del playground della chat di Studio AI aperto: in evidenza il nome della distribuzione e il pulsante per la visualizzazione del codice.

  4. Nel file .env, sostituire deployment_name con il nome della distribuzione del passaggio precedente. In questo esempio viene usato il nome distribuzione gpt-35-turbo-16k.

  5. Selezionare il pulsante <> Visualizza codice e copiare il valore dell'endpoint.

    Screenshot del popup di visualizzazione del codice: in evidenza il pulsante per copiare il valore dell'endpoint.

  6. Nel file .env, sostituire endpoint_value con il valore dell'endpoint copiato dalla finestra di dialogo nel passaggio precedente.

Avviso

L'autenticazione basata su chiavi è supportata, ma Microsoft la sconsiglia. Se si desidera usare chiavi, è possibile aggiungere la chiave a .env. Tuttavia è necessario accertare che .env si trovi nel file .gitignore, per assicurare che non venga accidentalmente archiviata nel repository Git.

Creare un prompt di chat e un'app di base

Creare prima di tutto un file modello di prompt. A tal fine si userà Prompty, ovvero il formato del modello di prompt supportato dal prompt flow.

Creare un file chat.prompty e copiare al suo interno il codice seguente:

---
name: Chat Prompt
description: A basic prompt that uses the chat API to answer questions
model:
    api: chat
    configuration:
        type: azure_openai
    parameters:
        max_tokens: 256
        temperature: 0.2
inputs:
    chat_input:
        type: string
    chat_history:
        type: list
        is_chat_history: true
        default: []
outputs:   
  response:
    type: string
sample:
    chat_input: What is the meaning of life?
---
system:
You are an AI assistant who helps people find information.

{% for item in history %}
{{item.role}}:
{{item.content}}
{% endfor %}

user:
{{chat_input}}

A questo punto si procede a creare un file Python che usa questo modello di richiesta. Creare un file denominato chat.py e incollarvi il codice seguente:

import os
from dotenv import load_dotenv
load_dotenv()

from promptflow.core import Prompty, AzureOpenAIModelConfiguration

model_config = AzureOpenAIModelConfiguration(
    azure_deployment=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT")
)

prompty = Prompty.load("chat.prompty", model={'configuration': model_config})
result = prompty(
    chat_history=[
        {"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},
        {"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."}
    ],
    chat_input="Do other Azure AI services support this too?")

print(result)

Ora, eseguire il codice Python dalla console:

python chat.py

Sarà ora visualizzato l'output dall'esecuzione di Prompty:

Yes, other Azure AI services also support various capabilities and features. Some of the Azure AI services include Azure Cognitive Services, Azure Machine Learning, Azure Bot Service, and Azure Databricks. Each of these services offers different AI capabilities and can be used for various use cases. If you have a specific service or capability in mind, feel free to ask for more details.

Tracciare l'esecuzione del codice della chat

Si esamini ora il modo in cui la traccia del prompt flow può fornire informazioni dettagliate sulle diverse chiamate LLM eseguite negli script di Python.

All'inizio del file chat.py, aggiungere il codice seguente per abilitare la traccia del prompt flow:

from promptflow.tracing import start_trace
start_trace()

Eseguire di nuovo chat.py:

python chat.py

Questa volta viene visualizzato un collegamento nell'output per visualizzare una traccia del prompt flow dell'esecuzione:

Starting prompt flow service...
Start prompt flow service on port 23333, version: 1.10.1.
You can stop the prompt flow service with the following command:'pf service stop'.
Alternatively, if no requests are made within 1 hours, it will automatically stop.
You can view the trace detail from the following URL:
http://localhost:23333/v1.0/ui/traces/?#collection=aistudio-python-quickstart&uiTraceId=0x59e8b9a3a23e4e8893ec2e53d6e1e521

Se si seleziona questo collegamento, sarà visualizzata la traccia che mostra i passaggi dell'esecuzione del programma, gli elementi passati a LLM e l'output della risposta.

Screenshot della traccia che mostra i passaggi dell'esecuzione del programma.

La traccia del prompt flow consente anche di tracciare chiamate di funzione specifiche e di registrare tracce in Studio AI. Per altre informazioni, vedere Come usare la traccia nell'SDK del prompt flow.

Valutare la richiesta

A questo punto sarà descritto l’uso dei valutatori del prompt flow per generare metriche in grado di assegnare punteggi sulla qualità della conversazione, secondo una scala da 0 a 5. Viene eseguito di nuovo il prompt, ma questa volta i risultati sono archiviati in una matrice contenente la conversazione completa. Poi la si passa a un ChatEvaluator per assegnare un punteggio.

Come prima cosa installare promptflow-evals package:

pip install promptflow-evals

Copiare ora il codice seguente in un file evaluate.py:

import os
from dotenv import load_dotenv
load_dotenv()

from promptflow.core import Prompty, AzureOpenAIModelConfiguration
from promptflow.evals.evaluators import ChatEvaluator

model_config = AzureOpenAIModelConfiguration(
    azure_deployment=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT")
)

chat_history=[
    {"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},
    {"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."}
]
chat_input="Do other Azure AI services support this too?"

prompty = Prompty.load("chat.prompty", model={'configuration': model_config})
response = prompty(chat_history=chat_history, chat_input=chat_input)

conversation = chat_history
conversation += [
    {"role": "user", "content": chat_input},
    {"role": "assistant", "content": response}
]

chat_eval = ChatEvaluator(model_config=model_config)
score = chat_eval(conversation=conversation)

print(score)

Eseguire lo script evaluate.py:

python evaluate.py

Sarà visualizzato un output del tipo:

{'gpt_coherence': 5.0, 'gpt_fluency': 5.0, 'evaluation_per_turn': {'gpt_coherence': {'score': [5.0, 5.0]}, 'gpt_fluency': {'score': [5.0, 5.0]}}}

A quanto pare, per questa conversazione le risposte da LLM hanno ottenuto un punteggio di coerenza e scorrevolezza pari a 5!

Per altre informazioni sull’uso dei valutatori del prompt flow, tra cui come creare valutatori personalizzati e registrare i risultati della valutazione in Studio AI, vedere Valutare l'app usando l'SDK del prompt flow.

Contenuto correlato