Erweiterte Szenarien für Telemetrie
Hinweis
In diesem Artikel wird das Aspire Dashboard zur Veranschaulichung verwendet. Wenn Sie andere Tools verwenden möchten, lesen Sie bitte die Dokumentation des Tools, das Sie in Setupanweisungen verwenden.
Automatische Funktionsaufrufe
Auto Function Calling ist ein Semantischer Kernel-Feature, mit dem der Kernel Funktionen automatisch ausführen kann, wenn das Modell mit Funktionsaufrufen antwortet, und die Ergebnisse zurück an das Modell liefern. Dieses Feature ist nützlich für Szenarien, in denen eine Abfrage mehrere Iterationen von Funktionsaufrufen erfordert, um eine endgültige Antwort auf natürliche Sprache zu erhalten. Weitere Details finden Sie in diesen GitHub-Beispielen.
Hinweis
Funktionsaufrufe werden von allen Modellen nicht unterstützt.
Tipp
Sie hören den Begriff "Tools" und "Toolaufrufe", die manchmal synonym mit "Funktionen" und "Funktionsaufrufen" verwendet werden.
Voraussetzungen
- Eine Azure OpenAI-Chatabschlussbereitstellung, die Funktionsaufrufe unterstützt.
- Docker
- Das neueste .Net SDK für Ihr Betriebssystem.
- Eine Azure OpenAI-Chatabschlussbereitstellung, die Funktionsaufrufe unterstützt.
- Docker
- Python 3.10, 3.11 oder 3.12 auf Ihrem Computer installiert.
Hinweis
Die semantische Kernel-Observability ist für Java noch nicht verfügbar.
Setup
Erstellen einer neuen Konsolenanwendung
Führen Sie in einem Terminal den folgenden Befehl aus, um eine neue Konsolenanwendung in C# zu erstellen:
dotnet new console -n TelemetryAutoFunctionCallingQuickstart
Navigieren Sie nach Abschluss des Befehls zum neu erstellten Projektverzeichnis.
Installieren erforderlicher Pakete
Semantischer Kernel
dotnet add package Microsoft.SemanticKernelOpenTelemetry Console Exporter
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
Erstellen einer einfachen Anwendung mit semantischem Kernel
Öffnen Sie die Program.cs Datei im Projektverzeichnis mit Ihrem bevorzugten Editor. Wir werden eine einfache Anwendung erstellen, die semantischen Kernel verwendet, um eine Eingabeaufforderung an ein Chatabschlussmodell zu senden. Ersetzen Sie den vorhandenen Inhalt durch den folgenden Code, und füllen Sie die erforderlichen Werte für deploymentName, endpointund apiKey:
using System.ComponentModel;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
namespace TelemetryAutoFunctionCallingQuickstart
{
class BookingPlugin
{
[KernelFunction("FindAvailableRooms")]
[Description("Finds available conference rooms for today.")]
public async Task<List<string>> FindAvailableRoomsAsync()
{
// Simulate a remote call to a booking system.
await Task.Delay(1000);
return ["Room 101", "Room 201", "Room 301"];
}
[KernelFunction("BookRoom")]
[Description("Books a conference room.")]
public async Task<string> BookRoomAsync(string room)
{
// Simulate a remote call to a booking system.
await Task.Delay(1000);
return $"Room {room} booked.";
}
}
class Program
{
static async Task Main(string[] args)
{
// Endpoint to the Aspire Dashboard
var endpoint = "http://localhost:4317";
var resourceBuilder = ResourceBuilder
.CreateDefault()
.AddService("TelemetryAspireDashboardQuickstart");
// Enable model diagnostics with sensitive data.
AppContext.SetSwitch("Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive", true);
using var traceProvider = Sdk.CreateTracerProviderBuilder()
.SetResourceBuilder(resourceBuilder)
.AddSource("Microsoft.SemanticKernel*")
.AddOtlpExporter(options => options.Endpoint = new Uri(endpoint))
.Build();
using var meterProvider = Sdk.CreateMeterProviderBuilder()
.SetResourceBuilder(resourceBuilder)
.AddMeter("Microsoft.SemanticKernel*")
.AddOtlpExporter(options => options.Endpoint = new Uri(endpoint))
.Build();
using var loggerFactory = LoggerFactory.Create(builder =>
{
// Add OpenTelemetry as a logging provider
builder.AddOpenTelemetry(options =>
{
options.SetResourceBuilder(resourceBuilder);
options.AddOtlpExporter(options => options.Endpoint = new Uri(endpoint));
// Format log messages. This is default to false.
options.IncludeFormattedMessage = true;
options.IncludeScopes = true;
});
builder.SetMinimumLevel(LogLevel.Information);
});
IKernelBuilder builder = Kernel.CreateBuilder();
builder.Services.AddSingleton(loggerFactory);
builder.AddAzureOpenAIChatCompletion(
deploymentName: "your-deployment-name",
endpoint: "your-azure-openai-endpoint",
apiKey: "your-azure-openai-api-key"
);
builder.Plugins.AddFromType<BookingPlugin>();
Kernel kernel = builder.Build();
var answer = await kernel.InvokePromptAsync(
"Reserve a conference room for me today.",
new KernelArguments(
new OpenAIPromptExecutionSettings {
ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions
}
)
);
Console.WriteLine(answer);
}
}
}
Im obigen Code definieren wir zunächst ein Simuliertes Konferenzraumbuchungs-Plug-In mit zwei Funktionen: FindAvailableRoomsAsync und BookRoomAsync. Anschließend erstellen wir eine einfache Konsolenanwendung, die das Plug-In für den Kernel registriert, und bitten den Kernel, die Funktionen bei Bedarf automatisch aufzurufen.
Erstellen einer neuen virtuellen Python-Umgebung
python -m venv telemetry-auto-function-calling-quickstart
Aktivieren Sie die virtuelle Umgebung.
telemetry-auto-function-calling-quickstart\Scripts\activate
Installieren erforderlicher Pakete
pip install semantic-kernel opentelemetry-exporter-otlp-proto-grpc
Erstellen eines einfachen Python-Skripts mit semantischem Kernel
Erstellen Sie ein neues Python-Skript, und öffnen Sie es mit Ihrem bevorzugten Editor.
New-Item -Path telemetry_auto_function_calling_quickstart.py -ItemType file
Wir werden ein einfaches Python-Skript erstellen, das semantic Kernel verwendet, um eine Eingabeaufforderung an ein Chatabschlussmodell zu senden. Ersetzen Sie den vorhandenen Inhalt durch den folgenden Code, und füllen Sie die erforderlichen Werte für deployment_name, endpointund api_key:
import asyncio
import logging
from typing import Annotated
from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.metrics import set_meter_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.metrics.view import DropAggregation, View
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.semconv.resource import ResourceAttributes
from opentelemetry.trace import set_tracer_provider
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
from semantic_kernel.functions.kernel_arguments import KernelArguments
from semantic_kernel.functions.kernel_function_decorator import kernel_function
class BookingPlugin:
@kernel_function(
name="find_available_rooms",
description="Find available conference rooms for today.",
)
def find_available_rooms(self,) -> Annotated[list[str], "A list of available rooms."]:
return ["Room 101", "Room 201", "Room 301"]
@kernel_function(
name="book_room",
description="Book a conference room.",
)
def book_room(self, room: str) -> Annotated[str, "A confirmation message."]:
return f"Room {room} booked."
# Endpoint to the Aspire Dashboard
endpoint = "http://localhost:4317"
# Create a resource to represent the service/sample
resource = Resource.create({ResourceAttributes.SERVICE_NAME: "telemetry-aspire-dashboard-quickstart"})
def set_up_logging():
exporter = OTLPLogExporter(endpoint=endpoint)
# Create and set a global logger provider for the application.
logger_provider = LoggerProvider(resource=resource)
# Log processors are initialized with an exporter which is responsible
# for sending the telemetry data to a particular backend.
logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
# Sets the global default logger provider
set_logger_provider(logger_provider)
# Create a logging handler to write logging records, in OTLP format, to the exporter.
handler = LoggingHandler()
# Add filters to the handler to only process records from semantic_kernel.
handler.addFilter(logging.Filter("semantic_kernel"))
# Attach the handler to the root logger. `getLogger()` with no arguments returns the root logger.
# Events from all child loggers will be processed by this handler.
logger = logging.getLogger()
logger.addHandler(handler)
logger.setLevel(logging.INFO)
def set_up_tracing():
exporter = OTLPSpanExporter(endpoint=endpoint)
# Initialize a trace provider for the application. This is a factory for creating tracers.
tracer_provider = TracerProvider(resource=resource)
# Span processors are initialized with an exporter which is responsible
# for sending the telemetry data to a particular backend.
tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
# Sets the global default tracer provider
set_tracer_provider(tracer_provider)
def set_up_metrics():
exporter = OTLPMetricExporter(endpoint=endpoint)
# Initialize a metric provider for the application. This is a factory for creating meters.
meter_provider = MeterProvider(
metric_readers=[PeriodicExportingMetricReader(exporter, export_interval_millis=5000)],
resource=resource,
views=[
# Dropping all instrument names except for those starting with "semantic_kernel"
View(instrument_name="*", aggregation=DropAggregation()),
View(instrument_name="semantic_kernel*"),
],
)
# Sets the global default meter provider
set_meter_provider(meter_provider)
# This must be done before any other telemetry calls
set_up_logging()
set_up_tracing()
set_up_metrics()
async def main():
# Create a kernel and add a service
kernel = Kernel()
kernel.add_service(AzureChatCompletion(
api_key="your-azure-openai-api-key",
endpoint="your-azure-openai-endpoint",
deployment_name="your-deployment-name"
))
kernel.add_plugin(BookingPlugin(), "BookingPlugin")
answer = await kernel.invoke_prompt(
"Reserve a conference room for me today.",
arguments=KernelArguments(
settings=PromptExecutionSettings(
function_choice_behavior=FunctionChoiceBehavior.Auto(),
),
),
)
print(answer)
if __name__ == "__main__":
asyncio.run(main())
Im obigen Code definieren wir zunächst ein Simuliertes Konferenzraumbuchungs-Plug-In mit zwei Funktionen: find_available_rooms und book_room. Anschließend erstellen wir ein einfaches Python-Skript, das das Plug-In für den Kernel registriert, und bitten den Kernel, die Funktionen bei Bedarf automatisch aufzurufen.
Umgebungsvariablen
Weitere Informationen zum Einrichten der erforderlichen Umgebungsvariablen zur Aktivierung des Kernels für KI-Connectors finden Sie in diesem Artikel .
Hinweis
Die semantische Kernel-Observability ist für Java noch nicht verfügbar.
Start the Aspire Dashboard
Folgen Sie den Anweisungen hier , um das Dashboard zu starten. Sobald das Dashboard ausgeführt wird, öffnen Sie einen Browser, und navigieren Sie zu http://localhost:18888 dem Dashboard.
Ausführung
Führen Sie die Konsolenanwendung mit dem folgenden Befehl aus:
dotnet run
Führen Sie das Python-Skript mit dem folgenden Befehl aus:
python telemetry_auto_function_calling_quickstart.py
Hinweis
Die semantische Kernel-Observability ist für Java noch nicht verfügbar.
Es sollte eine Ausgabe angezeigt werden, die Folgendem ähnelt:
Room 101 has been successfully booked for you today.
Überprüfen von Telemetriedaten
Wechseln Sie nach dem Ausführen der Anwendung zum Dashboard, um die Telemetriedaten zu überprüfen.
Suchen Sie die Ablaufverfolgung für die Anwendung auf der Registerkarte "Ablaufverfolgungen ". Sie sollten fünf Abschnitte in der Ablaufverfolgung umfassen:
Diese 5 Bereiche stellen die internen Vorgänge des Kernels dar, wobei automatischer Funktionsaufruf aktiviert ist. Zunächst wird das Modell aufgerufen, das einen Funktionsaufruf anfordert. Anschließend führt der Kernel die Funktion FindAvailableRoomsAsync automatisch aus und gibt das Ergebnis an das Modell zurück. Das Modell fordert dann einen weiteren Funktionsaufruf an, um eine Reservierung vorzunehmen, und der Kernel führt die Funktion BookRoomAsync automatisch aus und gibt das Ergebnis an das Modell zurück. Schließlich gibt das Modell eine natürliche Sprachantwort an den Benutzer zurück.
Und wenn Sie auf den letzten Bereich klicken und nach der Eingabeaufforderung im gen_ai.content.prompt Ereignis suchen, sollte folgendes angezeigt werden:
[
{ "role": "user", "content": "Reserve a conference room for me today." },
{
"role": "Assistant",
"content": null,
"tool_calls": [
{
"id": "call_NtKi0OgOllJj1StLkOmJU8cP",
"function": { "arguments": {}, "name": "FindAvailableRooms" },
"type": "function"
}
]
},
{
"role": "tool",
"content": "[\u0022Room 101\u0022,\u0022Room 201\u0022,\u0022Room 301\u0022]"
},
{
"role": "Assistant",
"content": null,
"tool_calls": [
{
"id": "call_mjQfnZXLbqp4Wb3F2xySds7q",
"function": { "arguments": { "room": "Room 101" }, "name": "BookRoom" },
"type": "function"
}
]
},
{ "role": "tool", "content": "Room Room 101 booked." }
]
Dies ist der Chatverlauf, der als Modell aufgebaut wird und der Kernel miteinander interagiert. Dies wird in der letzten Iteration an das Modell gesendet, um eine Antwort auf natürliche Sprache zu erhalten.
Suchen Sie die Ablaufverfolgung für die Anwendung auf der Registerkarte "Ablaufverfolgungen ". Sie sollten fünf Abschnitte in der Ablaufverfolgung gruppieren, die unter der AutoFunctionInvocationLoop Spanne gruppiert ist:
Diese 5 Bereiche stellen die internen Vorgänge des Kernels dar, wobei automatischer Funktionsaufruf aktiviert ist. Zunächst wird das Modell aufgerufen, das einen Funktionsaufruf anfordert. Anschließend führt der Kernel die Funktion find_available_rooms automatisch aus und gibt das Ergebnis an das Modell zurück. Das Modell fordert dann einen weiteren Funktionsaufruf an, um eine Reservierung vorzunehmen, und der Kernel führt die Funktion book_room automatisch aus und gibt das Ergebnis an das Modell zurück. Schließlich gibt das Modell eine natürliche Sprachantwort an den Benutzer zurück.
Und wenn Sie auf den letzten Bereich klicken und nach der Eingabeaufforderung im gen_ai.content.prompt Ereignis suchen, sollte folgendes angezeigt werden:
[
{ "role": "user", "content": "Reserve a conference room for me today." },
{
"role": "assistant",
"tool_calls": [
{
"id": "call_ypqO5v6uTRlYH9sPTjvkGec8",
"type": "function",
"function": {
"name": "BookingPlugin-find_available_rooms",
"arguments": "{}"
}
}
]
},
{
"role": "tool",
"content": "['Room 101', 'Room 201', 'Room 301']",
"tool_call_id": "call_ypqO5v6uTRlYH9sPTjvkGec8"
},
{
"role": "assistant",
"tool_calls": [
{
"id": "call_XDZGeTfNiWRpYKoHoH9TZRoX",
"type": "function",
"function": {
"name": "BookingPlugin-book_room",
"arguments": "{\"room\":\"Room 101\"}"
}
}
]
},
{
"role": "tool",
"content": "Room Room 101 booked.",
"tool_call_id": "call_XDZGeTfNiWRpYKoHoH9TZRoX"
}
]
Dies ist der Chatverlauf, der als Modell aufgebaut wird und der Kernel miteinander interagiert. Dies wird in der letzten Iteration an das Modell gesendet, um eine Antwort auf natürliche Sprache zu erhalten.
Hinweis
Die semantische Kernel-Observability ist für Java noch nicht verfügbar.
Fehlerbehandlung
Wenn während der Ausführung einer Funktion ein Fehler auftritt, fängt der Kernel den Fehler automatisch ab und gibt eine Fehlermeldung an das Modell zurück. Das Modell kann dann diese Fehlermeldung verwenden, um dem Benutzer eine Natürliche Sprachantwort bereitzustellen.
Ändern Sie die BookRoomAsync Funktion im C#-Code, um einen Fehler zu simulieren:
[KernelFunction("BookRoom")]
[Description("Books a conference room.")]
public async Task<string> BookRoomAsync(string room)
{
// Simulate a remote call to a booking system.
await Task.Delay(1000);
throw new Exception("Room is not available.");
}
Führen Sie die Anwendung erneut aus, und beobachten Sie die Ablaufverfolgung im Dashboard. Sie sollten die Spanne sehen, die den Kernelfunktionsaufruf mit einem Fehler darstellt:
Hinweis
Es ist sehr wahrscheinlich, dass die Modellantworten auf den Fehler bei jeder Ausführung der Anwendung variieren können, da das Modell stochastisch ist. Möglicherweise sehen Sie, dass das Modell alle drei Zimmer gleichzeitig reserviert oder zum ersten Mal reserviert, dann die anderen beiden das zweite Mal reservieren usw.
Ändern Sie die book_room Funktion im Python-Code, um einen Fehler zu simulieren:
@kernel_function(
name="book_room",
description="Book a conference room.",
)
async def book_room(self, room: str) -> Annotated[str, "A confirmation message."]:
# Simulate a remote call to a booking system
await asyncio.sleep(1)
raise Exception("Room is not available.")
Führen Sie die Anwendung erneut aus, und beobachten Sie die Ablaufverfolgung im Dashboard. Sie sollten die Spanne sehen, die den Kernel-Funktionsaufruf mit einem Fehler und der Stapelablaufverfolgung darstellt:
Hinweis
Es ist sehr wahrscheinlich, dass die Modellantworten auf den Fehler bei jeder Ausführung der Anwendung variieren können, da das Modell stochastisch ist. Möglicherweise sehen Sie, dass das Modell alle drei Zimmer gleichzeitig reserviert oder zum ersten Mal reserviert, dann die anderen beiden das zweite Mal reservieren usw.
Hinweis
Die semantische Kernel-Observability ist für Java noch nicht verfügbar.
Nächste Schritte und weiteres Lesen
In der Produktion erhalten Ihre Dienste möglicherweise eine große Anzahl von Anforderungen. Der semantische Kernel generiert eine große Menge an Telemetriedaten. einige davon sind für Ihren Anwendungsfall möglicherweise nicht nützlich und führen unnötige Kosten zum Speichern der Daten ein. Sie können die Samplingfunktion verwenden, um die Menge der gesammelten Telemetriedaten zu verringern.
Die Observierbarkeit im semantischen Kernel wird ständig verbessert. Sie finden die neuesten Updates und neuen Features im GitHub-Repository.