Trace Span Spezifikation#

Experimentelles Feature

Dies ist eine experimentelle Funktion und kann sich jederzeit ändern. Erfahren Sie mehr.

Dieses Dokument beschreibt das Design von Promptflow-Spans und detailliert, welche Informationen getraced und wie sie strukturiert werden.

Einleitung#

Der Span, wie Sie vielleicht wissen, ist die Grundeinheit des Trace-Systems und repräsentiert eine Einheit, die Ausführungsinformationen im Promptflow-System erfasst. Spans werden in einer Eltern-Kind-Beziehung verschachtelt und durch Link-Beziehungen gepaart, was Entwicklern und Benutzern einen umfassenden Überblick über den Ausführungsprozess der Anwendung verschafft.

Durch die Einhaltung dieser Spezifikationen gewährleisten wir Transparenz und Konsistenz in unserem Tracing-System.

Die Benutzeroberfläche interpretiert die erfassten Spans und präsentiert sie benutzerfreundlich. Das Verständnis der Felder und Verträge, die in den Spans definiert sind, ist unerlässlich, um Promptflow effektiv nutzen oder seine Komponenten integrieren zu können.

OpenTelemetry Span Grundlagen#

Ein typisches Span-Objekt enthält die folgenden Informationen

Feld

Beschreibung

name

Name des Spans

parent_id

Übergeordneter Span-ID (leer für Root-Spans)

context

Span-Kontext

start_time

Startzeit des Spans

end_time

Endzeit des Spans

status

Span-Status

attributes

Attribute

events

Span-Ereignisse

links

Span-Links

Span in Promptflow#

In Promptflow definieren wir mehrere Span-Typen, und das System erstellt automatisch Spans mit Ausführungsinformationen in ausgewiesenen Attributen und Ereignissen.

Diese Span-Typen teilen gemeinsame Attribute und Ereignisse, die wir als Standardattribute und -ereignisse bezeichnen. Lassen Sie uns diese gemeinsamen Elemente untersuchen, bevor wir uns den Besonderheiten jedes Span-Typs widmen.

Gemeinsame Attribute und Ereignisse#

Attribute#

Jeder Span in Promptflow wird mit einer Reihe von Standardattributen angereichert, die wesentliche Informationen über den Kontext und Zweck des Spans liefern. Die folgende Tabelle listet diese Attribute auf

Attribut

Typ

Beschreibung

Examples

Anforderungsniveau

framework

string

Dieses Attribut gibt das Framework an, in dem der Trace aufgezeichnet wurde. Für unser Projekt ist dieser Wert konstant auf promptflow gesetzt.

promptflow

Erforderlich

node_name

string

Bezeichnet den Namen des Flow-Knotens.

chat

Bedingt erforderlich, wenn der Flow ein Directed Acyclic Graph (DAG) Flow ist.

span_type

string

Gibt den Typ des Spans an, z. B. LLM oder Flow. Siehe hier für Details.

LLM

Erforderlich

line_run_id

string

Eindeutiger Bezeichner für den Ausführungsdurchlauf innerhalb von Promptflow.

d23159d5-cae0-4de6-a175-295c715ce251

Erforderlich

Funktion

string

Die Funktion, die dem Span zugeordnet ist.

search

Empfohlen

session_id

string

Eindeutiger Bezeichner für Chat-Sitzungen.

4ea1a462-7617-439f-a40c-12a8b93f51fb

Opt-In

referenced.line_run_id

string

Repräsentiert die Line-Run-ID, die die Quelle des Evaluierungsdurchlaufs ist.

f747f7b8-983c-4bf2-95db-0ec3e33d4fd1

Bedingt erforderlich, nur in Evaluierungsdurchläufen verwendet – Durchläufe auf Evaluierungsflows.

batch_run_id

string

Die Batch-Run-ID im Batch-Modus.

61daff70-80d5-4e79-a50b-11b38bb3d344

Bedingt erforderlich, nur in Batch-Durchläufen verwendet.

referenced.batch_run_id

string

Gibt die Batch-Run-ID an, gegen die ein Evaluierungsflow ausgeführt wurde.

851b32cb-545c-421d-8e51-0a3ea66f0075

Bedingt erforderlich, nur in Evaluierungsdurchläufen verwendet.

line_number

int

Die Zeilennummer innerhalb eines Batch-Durchlaufs, beginnend bei 0.

1

Bedingt erforderlich, nur in Batch-Durchläufen verwendet.

__computed__.cumulative_token_count.prompt

int

Kumulative Tokenanzahl von Kindknoten für Prompts. [1]

200

Empfohlen

__computed__.cumulative_token_count.completion

int

Kumulative Tokenanzahl von Kindknoten für Completion-Antworten. [1]

80

Empfohlen

__computed__.cumulative_token_count.total

int

Gesamte kumulative Tokenanzahl für Prompts und Completions. [1]

120

Empfohlen

[1]: Kumulative Tokenanzahlen werden in der Span-Hierarchie nach oben weitergegeben, sodass jeder Span die Gesamtzahl der Token aller LLM-Ausführungen in seinem Bereich widerspiegelt.

Ereignisse#

In Promptflow folgen die vom Promptflow-Framework emittierten Ereignisse dem unten stehenden Format

  • event MUSS Attribute haben

  • event-Attribute MÜSSEN einen Schlüssel namens payload enthalten, der sich auf die innerhalb eines Ereignisses übermittelten Daten bezieht.

  • event-Attribute payload MUSS ein JSON-String sein, der ein Objekt repräsentiert.

Ereignis

Payload-Beschreibung

Payload-Beispiele

Anforderungsniveau

promptflow.function.inputs

Input eines Funktionsaufrufs

{"chat_history":[],"question":"What is ChatGPT?"}

Erforderlich

promptflow.function.output

Output eines Funktionsaufrufs

{"answer":"ChatGPT is a conversational AI model developed by OpenAI."}

Erforderlich

Span-Typen Spezifikation#

Innerhalb des Promptflow-Systems haben wir mehrere unterschiedliche Span-Typen definiert, um verschiedene Ausführungseinheiten abzudecken. Jeder Span-Typ ist darauf ausgelegt, spezifische Ausführungsinformationen zu erfassen und ergänzt die Standardattribute und -ereignisse. Derzeit umfasst unser System die folgenden Span-Typen: LLM, Function, LangChain, Flow, Embedding und Retrieval.

Über die Standardattribute und -ereignisse hinaus besitzt jeder Span-Typ ausgewiesene Felder zur Speicherung relevanter, für seine Rolle im System spezifischer Informationen. Diese spezialisierten Attribute und Ereignisse stellen sicher, dass alle relevanten Daten sorgfältig getraced und zur Analyse verfügbar sind.

LLM#

Der LLM (Large Language Model) Span erfasst detaillierte Ausführungsinformationen von Aufrufen großer Sprachmodelle.

Attribut

Typ

Beschreibung

Examples

Anforderungsniveau

span_type

string

Identifiziert den Span als LLM-Typ.

LLM

Erforderlich

llm.usage.total_tokens

int

Gesamtzahl der verwendeten Token, einschließlich Prompt- und Antwort-Token.

180

Erforderlich

llm.usage.prompt_tokens

int

Anzahl der Token, die im Prompt des LLM verwendet wurden.

100

Erforderlich

llm.usage.completion_tokens

int

Anzahl der Token, die in der LLM-Antwort (Completion) verwendet wurden.

80

Erforderlich

llm.response.model

string

Gibt das LLM an, das die Antwort generiert hat.

gpt-4

Erforderlich

Ereignis

Payload-Beschreibung

Payload-Beispiele

Anforderungsniveau

promptflow.llm.generated_message

Erfasst die Ausgabennachricht eines LLM-Aufrufs.

{"content":"ChatGPT is a conversational AI model developed by OpenAI.","role":"assistant","function_call":null,"tool_calls":null}

Erforderlich

Hinweis: OpenTelemetry definiert derzeit mehrere LLM-bezogene Span-Attribute und -Ereignisse als semantische Konventionen. Wir planen, uns zukünftig an diese Konventionen anzulehnen. Weitere Informationen finden Sie unter Semantische Konventionen für GenAI-Operationen.

Funktion#

Der Function Span ist ein vielseitiger Standard-Span in Promptflow, der dazu dient, eine breite Palette von allgemeinen Funktionsausführungsinformationen zu erfassen.

Attribut

Typ

Beschreibung

Examples

Anforderungsniveau

span_type

string

Identifiziert den Span als Funktionstyp.

Funktion

Erforderlich

Ereignis

Payload-Beschreibung

Payload-Beispiele

Anforderungsniveau

promptflow.prompt.template

Details zum Prompt-Template und zu Variablen.

{"prompt.template":"# system:\nYou are a helpful assistant.\n\n# user:\n{{question}}","prompt.variables":"{\n "question": "What is ChatGPT?"\n}"}

Bedingt erforderlich, wenn die Funktion eine Prompt-Template-Formatierung enthält. [1]

[1]: Template-Formatierung ist ein Prozess der Auflösung eines Prompt-Templates in eine Prompt-Nachricht. Dieser Prozess kann innerhalb einer Funktion stattfinden, die einen LLM-Aufruf auslöst.

Flow#

Der Flow Span kapselt die Ausführungsdetails eines Flows innerhalb von Promptflow.

Attribut

Typ

Beschreibung

Examples

Anforderungsniveau

span_type

string

Bezeichnet den Span als Flow-Typ.

Flow

Erforderlich

Embedding#

Der Embedding Span dient der Erfassung von Details zu Embedding-Aufrufen innerhalb von Promptflow.

Attribut

Typ

Beschreibung

Examples

Anforderungsniveau

span_type

string

Bezeichnet den Span als Embedding-Typ.

Embedding

Erforderlich

llm.usage.total_tokens

int

Gesamtzahl der verwendeten Token, Summe aus Prompt- und Antwort-Token.

180

Erforderlich

llm.usage.prompt_tokens

int

Anzahl der Token, die im Prompt für den Embedding-Aufruf verwendet wurden.

100

Erforderlich

llm.usage.completion_tokens

int

Anzahl der Token, die in der Antwort vom Embedding-Aufruf verwendet wurden.

80

Erforderlich

llm.response.model

string

Identifiziert das LLM-Modell, das zur Generierung des Embeddings verwendet wurde.

text-embedding-ada-002

Erforderlich

Ereignis

Payload-Beschreibung

Payload-Beispiele

Anforderungsniveau

promptflow.embedding.embeddings

Details zu den durch einen Aufruf generierten Embeddings.

[{"embedding.vector":"","embedding.text":"When does a pipeline job reuse a previous job's results in Azure Machine Learning?"}]

Erforderlich

Retrieval#

Der Retrieval Span-Typ ist speziell dafür konzipiert, die Ausführungsdetails einer Retrieval-Aufgabe innerhalb von Promptflow zu kapseln.

Attribut

Typ

Beschreibung

Examples

Anforderungsniveau

span_type

string

Kennzeichnet den Span als Retrieval-Typ.

Retrieval

Erforderlich

Ereignis

Payload-Beschreibung

Payload-Beispiele

Anforderungsniveau

promptflow.retrieval.query

Erfasst den Text der Retrieval-Abfrage.

"When does a pipeline job reuse a previous job's results in Azure Machine Learning?"

Erforderlich

promptflow.retrieval.documents

Details zur Liste der abgerufenen Dokumente, die für die Abfrage relevant sind.

[{"document.id":"https://componentsdk.azurewebsites.net/howto/caching-reuse.html","document.score":2.677619457244873,"document.content":"# Component concepts &..."},{"document.id":"https://learn.microsoft.com/en-us/azure/machine-learning/v1/reference-pipeline-yaml","document.score":2.563112735748291,"document.content":"etc. |\r\n| runconfig | T..."}]

Erforderlich