Abilitare la traccia e raccogliere commenti e suggerimenti per una distribuzione del flusso (anteprima)

Nota

Questa funzionalità è attualmente in anteprima pubblica. 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.

Dopo aver distribuito un'APP di intelligenza artificiale generativa nell'ambiente di produzione, gli sviluppatori di app cercano di migliorare la comprensione e ottimizzare le prestazioni. I dati di traccia per ogni richiesta, metriche aggregate e feedback degli utenti svolgono ruoli critici.

Questo articolo illustra come abilitare la traccia, raccogliere metriche aggregate e feedback degli utenti durante il tempo di inferenza della distribuzione del flusso.

Prerequisiti

• L'interfaccia della riga di comando di Azure e l'estensione di Azure Machine Learning per l'interfaccia della riga di comando di Azure. Per altre informazioni, vedere Installare, configurare e usare l'interfaccia della riga di comando (v2).
• Un'area di lavoro di Azure Machine Learning. Se non è disponibile, seguire la procedura descritta nell'articolo Avvio rapido: Creare risorse dell'area di lavoro per crearne una.
• An Application Insights. In genere un'area di lavoro di Machine Learning ha un'applicazione collegata predefinita. Se si vuole usarne uno nuovo, è possibile creare una risorsa di Application Insights.
• Informazioni su come creare e testare un flusso nel prompt flow.
• Avere una conoscenza di base sugli endpoint online gestiti. Gli endpoint online gestiti funzionano con potenti macchine CPU e GPU in Azure in modo scalabile e completamente gestito librando l'utente dalle attività di configurazione e gestione dell'infrastruttura di distribuzione sottostante. Per altre informazioni sugli endpoint online gestiti, vedere Endpoint e distribuzioni online per l'inferenza in tempo reale.
• I controlli degli accessi in base al ruolo di Azure vengono usati per concedere l'accesso alle operazioni in Azure Machine Learning. Per eseguire la procedura descritta in questo articolo, all'account utente deve essere assegnato il ruolo di proprietario o collaboratore per l'area di lavoro di Azure Machine Learning oppure un ruolo personalizzato che consenta "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/". Se si usa Studio per creare/gestire endpoint/distribuzioni online, è necessaria un'altra autorizzazione "Microsoft.Resources/deployments/write" dal proprietario del gruppo di risorse. Per altre informazioni, vedere Gestire l'accesso a un'area di lavoro di Azure Machine Learning.

Distribuire un flusso per l'inferenza in tempo reale

Dopo aver testato correttamente il flusso, un flusso flessibile o un flusso DAG, è possibile distribuire il flusso nell'ambiente di produzione. In questo articolo viene usato come esempio distribuire un flusso agli endpoint online gestiti di Azure Machine Learning. Per i flussi flessibili, è necessario preparare il flow.flex.yaml file anziché flow.dag.yaml.

È anche possibile eseguire la distribuzione in altre piattaforme, ad esempio il contenitore Docker, il cluster Kubernetes e così via.

Nota

È necessario usare l'immagine di base del flusso di richiesta più recente per distribuire il flusso, in modo che supporti l'API di raccolta di traccia e feedback.

Abilitare la traccia e raccogliere le metriche di sistema per la distribuzione

Se si usa l'interfaccia utente di Studio per la distribuzione, è possibile attivare la diagnostica di Application Insights in Impostazioni avanzate -> Passaggio distribuzione nella distribuzione guidata, in cui i dati di traccia e le metriche di sistema vengono raccolti nell'area di lavoro collegata ad Application Insights.

Se si usa l'SDK o l'interfaccia della riga di comando, è possibile aggiungere una proprietà app_insights_enabled: true nel file yaml di distribuzione che raccoglierà i dati nell'area di lavoro collegata ad Application Insights. È anche possibile specificare altre application insights da una variabile APPLICATIONINSIGHTS_CONNECTION_STRING di ambiente nel file yaml di distribuzione come indicato di seguito. È possibile trovare il stringa di connessione di Application Insights nella pagina Panoramica in portale di Azure.

# below is the property in deployment yaml
# app_insights_enabled: true

# you can also use the environment variable
environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Nota

Se si imposta app_insights_enabled: true solo ma l'area di lavoro non ha un application insights collegato, la distribuzione non avrà esito negativo, ma non verranno raccolti dati.

Se si specificano sia che app_insights_enabled: true la variabile di ambiente precedente contemporaneamente, i dati di traccia e le metriche verranno inviati all'area di lavoro collegata ad Application Insights. Pertanto, se si vuole specificare un'applicazione diversa, è sufficiente mantenere la variabile di ambiente.

Se si esegue la distribuzione in altre piattaforme, è anche possibile usare la variabile APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string> di ambiente per raccogliere dati di traccia e metriche in Application Insights speicifed.

Visualizzare i dati di traccia in Application Insights

Le tracce registrano eventi specifici o lo stato di un'applicazione durante l'esecuzione. Può includere dati sulle chiamate di funzione, i valori delle variabili, gli eventi di sistema e altro ancora. Le tracce consentono di suddividere i componenti di un'applicazione in input e output discreti, che è fondamentale per il debug e la comprensione di un'applicazione. Per altre informazioni, vedere Tracce OpenTelemetry sulle tracce. I dati di traccia seguono la specifica OpenTelemetry.

È possibile visualizzare la traccia dettagliata in Application Insights specificato. Lo screenshot seguente mostra un esempio di evento di un flusso distribuito contenente più nodi. In Application Insights -> Ricerca di analisi -> Transazione ed è possibile selezionare ogni nodo per visualizzarne la traccia dettagliata.

Il record degli eventi del tipo di dipendenza registra le chiamate dalle distribuzioni. Il nome dell'evento è il nome della cartella del flusso. Altre informazioni sulla ricerca e la diagnostica delle transazioni in Application Insights.

Visualizzare le metriche di sistema in Application Insights

Nome metriche	Type	Dimensioni	Descrizione
token_consumption	counter	- flow - node - llm_engine - token_type: : prompt_tokenstoken di input dell'API LLM; completion_tokens: token di risposta API LLM; total_tokens = prompt_tokens + completion tokens	Metriche di consumo dei token OpenAI
flow_latency	histogram	flusso, response_code, streaming, response_type	costo di esecuzione della richiesta, response_type indica se è full/firstbyte/lastbyte
flow_request	counter	flusso, response_code, eccezione, streaming	Numero di richieste di flusso
node_latency	histogram	flow, node, run_status	Costo di esecuzione del nodo
node_request	counter	flow, node, exception, run_status	Numero di esecuzioni del nodo
rpc_latency	histogram	flow, node, api_call	Costo RPC
rpc_request	counter	flow, node, api_call, exception	Numero RPC
flow_streaming_response_duration	histogram	flusso	Costo di invio della risposta di streaming, dall'invio del primo byte all'invio dell'ultimo byte

È possibile trovare l'area di lavoro predefinita di Application Insights nella pagina di panoramica dell'area di lavoro in portale di Azure.

Aprire Application Insights e selezionare Utilizzo e costi stimati nel riquadro di spostamento a sinistra. Selezionare Metriche personalizzate (anteprima), quindi selezionare Con dimensioni e salvare la modifica.

Selezionare la scheda Metriche nel riquadro di spostamento a sinistra. Selezionare Metriche standard del prompt flow nello Spazio dei nomi della metrica. È possibile esplorare le metriche dall'elenco a discesa Metrica con diversi metodi di aggregazione.

Raccogliere commenti e suggerimenti e inviarli ad Application Insights

La gestione del flusso di prompt fornisce una nuova /feedback API che consente ai clienti di raccogliere il feedback, il payload del feedback può essere qualsiasi dato in formato JSON, pf serve solo per consentire al cliente di salvare i dati di feedback in un intervallo di traccia. I dati verranno salvati nel cliente di destinazione dell'utilità di esportazione di traccia configurato. Supporta anche la propagazione del contesto di traccia standard OpenTelemetry, che indica che rispetta il contesto di traccia impostato nell'intestazione della richiesta e lo usa come contesto dell'intervallo padre della richiesta. È possibile sfruttare la funzionalità di traccia distribuita per correlare la traccia feedback alla relativa traccia delle richieste di chat.

Di seguito è riportato il codice di esempio che illustra come assegnare un punteggio a un endpoint gestito distribuito abilitato per la traccia e inviare il feedback allo stesso intervallo di traccia della richiesta di assegnazione dei punteggi. Il flusso ha input question e chat_hisotrye e output answer. Dopo aver assegnato il punteggio all'endpoint, viene raccolto un feedback e inviato ad Application Insights specificato durante la distribuzione del flusso. È necessario compilare il api_key valore o modificare il codice in base al caso d'uso.

import urllib.request
import json
import os
import ssl
from opentelemetry import trace, context
from opentelemetry.baggage.propagation import W3CBaggagePropagator
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
from opentelemetry.sdk.trace import TracerProvider

# Initialize your tracer
tracer = trace.get_tracer("my.genai.tracer")
trace.set_tracer_provider(TracerProvider())

# Request data goes here
# The example below assumes JSON formatting which may be updated
# depending on the format your endpoint expects.
# More information can be found here:
# https://docs.microsoft.com/azure/machine-learning/how-to-deploy-advanced-entry-script
data = {
    "question": "hello",
    "chat_history": []
}

body = str.encode(json.dumps(data))

url = 'https://basic-chat-endpoint.eastus.inference.ml.azure.com/score'
feedback_url = 'https://basic-chat-endpoint.eastus.inference.ml.azure.com/feedback'
# Replace this with the primary/secondary key, AMLToken, or Microsoft Entra ID token for the endpoint
api_key = ''
if not api_key:
    raise Exception("A key should be provided to invoke the endpoint")

# The azureml-model-deployment header will force the request to go to a specific deployment.
# Remove this header to have the request observe the endpoint traffic rules
headers = {'Content-Type':'application/json', 'Authorization':('Bearer '+ api_key), 'azureml-model-deployment': 'basic-chat-deployment' }

try:
    with tracer.start_as_current_span('genai-request') as span:

        ctx = context.get_current()
        TraceContextTextMapPropagator().inject(headers, ctx)
        print(headers)
        print(ctx)
        req = urllib.request.Request(url, body, headers)
        response = urllib.request.urlopen(req)

        result = response.read()
        print(result)

        # Now you can process the answer and collect feedback
        feedback = "thumbdown"  # Example feedback (modify as needed)

        # Make another request to save the feedback
        feedback_body = str.encode(json.dumps(feedback))
        feedback_req = urllib.request.Request(feedback_url, feedback_body, headers)
        urllib.request.urlopen(feedback_req)


except urllib.error.HTTPError as error:
    print("The request failed with status code: " + str(error.code))

    # Print the headers - they include the requert ID and the timestamp, which are useful for debugging the failure
    print(error.info())
    print(error.read().decode("utf8", 'ignore'))

È possibile visualizzare la traccia della richiesta insieme ai commenti e suggerimenti in Application Insights.

Utilizzo avanzato: esportare la traccia nel servizio dell'agente di raccolta OpenTelemetry personalizzato

In alcuni casi, è possibile esportare i dati di traccia nel servizio agente di raccolta OTel distribuito, abilitato impostando "OTEL_EXPORTER_OTLP_ENDPOINT". Usare questo utilità di esportazione quando si vuole personalizzare la logica di elaborazione dell'intervallo e la propria destinazione persistente di traccia.

Passaggi successivi

• Risolvere gli errori degli endpoint online gestiti.
• Distribuire un flusso in altre piattaforme, ad esempio Docker.