Konversationen¶
Evaluieren Sie Multi-Turn-Dialoge und konversationsabhängige Prompts mit systematischem Kontextmanagement
Konversationen ermöglichen es Ihnen, Prompts zu testen, die einen Gesprächsverlauf oder Multi-Turn-Dialogkontext erfordern. Egal, ob Sie Chatbots, Kundensupport-Systeme oder eine beliebige LLM-Anwendung erstellen, die den Kontext über mehrere Interaktionen hinweg beibehält – mit der Konversationsfunktion können Sie systematisch evaluieren, wie Ihre Prompts mit unterschiedlichen Gesprächsverläufen umgehen.
Was sind Konversationen?¶
Konversationen in elluminate sind strukturierte Nachrichtenverläufe, die Kontext für die Prompt-Evaluierung bieten. Anstatt Prompts isoliert zu testen, ermöglichen Ihnen Konversationen Folgendes:
- Testen von Multi-Turn-Dialogen – Evaluieren Sie, wie Ihr LLM und Ihr Prompt mit laufenden Gesprächen umgehen.
- Bereitstellung des Gesprächsverlaufs – Geben Sie Ihrem LLM den Kontext früherer Nachrichten.
- Evaluierung des Kontextbewusstseins – Überprüfen Sie, ob Ihr Prompt die Kohärenz über mehrere Gesprächsrunden hinweg beibehält.
- Testen mit realistischen Szenarien – Verwenden Sie tatsächliche Gesprächsprotokolle aus Ihrem System.
Eine Konversation wird als spezielles Format in Ihrer Collection gespeichert, welches Folgendes enthält:
- Messages – Der Gesprächsverlauf (System-, Benutzer-, Assistenten-, Tool-Nachrichten)
- Tools (optional) – Tool-Definitionen, die während der Konversation verfügbar sind
- Tool choice (optional) – Wie das Modell Tools verwenden soll
- Response format (optional) – Anforderungen an die strukturierte Ausgabe
- Metadata (optional) – Zusätzliche Konfigurationen wie Merge-Modi
Wie Konversationen funktionieren¶
Die Conversation-Spalte¶
Konversationen werden in einem speziellen Spaltentyp Conversation in Ihren Collections gespeichert. Diese Spalte:
- Enthält strukturierte Konversations-Formate (keinen reinen Text)
- Darf nur einmal pro Collection existieren
- Kann nicht gleichzeitig mit "Direkte Eingabe"-Spalten existieren
- Kann nach der Erstellung nicht umbenannt werden
Die Direkte Eingabe-Spalte¶
Direkte Eingaben stehen im Kontrast zu Konversationen und sind ein einzelner Prompt der an ein LLM gesendet wird. Der Wert einer Direkten Eingabe unterstützt selbst keine Platzhalter, und eine Direkte Eingabe-Spalte kann nicht zusammen mit einer Konversations-Spalte verwendet werden.
Direkte Eingaben vereinfachen es spezifische Varianten von Prompts direkt gegen ein LLM zu testen. Sie können optional mit einem Prompt Template kombiniert werden: sind beide vorhanden, werden zuerst die gerenderten Template-Nachrichten gesendet (typischerweise ein System-Prompt) und die Direkte Eingabe wird als abschließende User-Nachricht angehängt. Die Platzhalter des Templates müssen durch andere Spalten der Collection abgedeckt sein — ein Template nur mit System-Prompt (ohne Platzhalter) ist immer kompatibel.
Auf der technischen Ebene sind direkte Eingaben eine vereinfachte Form von Konversationen mit einer einzelnen Nutzer-Nachricht.
Nachrichtenfluss¶
Wenn Sie ein Experiment mit Konversationen durchführen, führt elluminate folgende Schritte aus:
- Fügt optional Ihr Template hinzu – Falls vorhanden, füllen wir Ihre Prompt Template-Platzhalter mit Werten aus der Collection.
- Hängt Konversationsnachrichten an – Fügt den Gesprächsverlauf nach dem Prompt Template hinzu.
- Sendet an das LLM – Das Modell sieht den vollständig konstruierten Nachrichtenverlauf.
- Evaluiert die Response – Wir bewerten basierend auf Criteria mit vollem Konversationskontext.
Beispiel für die Nachrichtenreihenfolge:
1. System-Nachricht aus dem Template
2. User-Nachricht aus dem Template (mit ausgefüllten Platzhaltern)
3. User-Nachricht aus dem Konversations-Format
4. Assistant-Nachricht aus dem Konversations-Format
5. User-Nachricht aus dem Konversations-Format
-> LLM generiert hier die Response
Einrichten von Konversationen¶
Schritt 1: Erstellen einer Collection mit einer Conversation-Spalte¶
Über die UI¶
- Navigieren Sie zu den Collections Ihres Projects.
- Klicken Sie auf "Neue Collection" oder öffnen Sie eine bestehende Collection.
- Klicken Sie auf die Schaltfläche "Spalte hinzufügen" (+ Symbol) in der Tabellenkopfzeile.
- Konfigurieren Sie die Spalte:
- Name: Wählen Sie einen beschreibenden Namen (z. B.
conversation,chat_history). - Type: Wählen Sie "Konversation".
- Default Value: Leer lassen (Konversations-Spalten verwenden derzeit keine Standardwerte).
Einschränkungen für Konversations-Spalten:
- Nur eine Konversations-Spalte pro Collection.
- Kann nicht gleichzeitig mit einer "Direkte Eingabe"-Spalte existieren.
- Der Spaltenname kann nach der Erstellung nicht geändert werden.
- Muss gültige Konversations-Formate enthalten.
Direkte Eingabe + Prompt Template
Eine Direkte Eingabe-Spalte kann mit einem Prompt Template kombiniert werden (typischerweise einem System-Prompt). Das Template wird zuerst gerendert, anschließend wird die Direkte Eingabe als abschließende User-Nachricht angehängt.
Schritt 2: Konversationsdaten hinzufügen¶
Format der Konversationen¶
Konversationen werden als Unified Conversation Envelope (UCE) gespeichert — ein schema-versionierter Wrapper um Chat-Nachrichten im OpenAI-Format, ergänzt um optionale Tools, Tool Choice, Response Format und Metadata.
UCE oder ATIF?
UCE beschreibt eine Konversation, die elluminate ausführen und bewerten soll. Um einen Agent-Lauf zu bewerten, den Sie bereits ausgeführt haben, laden Sie stattdessen dessen Trajectory im ATIF-Format hoch — siehe Das Trajectory-Format.
Payloads mit dem SDK erstellen
Das native Nachrichtenformat von elluminate ist das OpenAI Chat-Nachrichtenformat, daher wandelt das SDK einen OpenAI Chat-Completions-Request für Sie in ein UCE Payload um. Verwenden Sie UCEPayloadV1.from_openai(...).to_uce_dict(), anstatt das Envelope von Hand zusammenzubauen:
from elluminate.schemas import UCEPayloadV1
conversation = UCEPayloadV1.from_openai(
messages=[
{"role": "user", "content": "Hallo!"},
{"role": "assistant", "content": "Hi! Wie kann ich helfen?"},
{"role": "user", "content": "Ich brauche Hilfe mit meinem Account."},
],
).to_uce_dict()
from_openai validiert die messages im OpenAI-Format (sowie die optionalen Keyword-Argumente tools, tool_choice, response_format, attachments und metadata) und verpackt sie im Envelope. to_uce_dict() liefert den JSON-fertigen Wert, den Sie in einer Conversation-Spalte speichern. Ein vollständiges End-to-End-Beispiel finden Sie in den SDK-Beispielen.
Referenz des Wire-Formats
Das rohe Envelope benötigen Sie nur beim Einfügen über die UI oder beim Vorbereiten eines JSONL-Uploads — der Converter erzeugt genau diese Struktur (alles außer messages ist optional):
{
"schema_version": "elluminate.uce/1",
"input": {
"messages": [
{"role": "user", "content": "Hallo!"},
{"role": "assistant", "content": "Hi! Wie kann ich helfen?"},
{"role": "user", "content": "Ich brauche Hilfe mit meinem Account."}
],
"tools": [...],
"tool_choice": "auto",
"response_format": {...},
"metadata": {...}
}
}
Ein reines Messages-Array wird ebenfalls als Kurzform für ein Envelope ohne Optionen akzeptiert:
Rollen¶
Nachrichten unterstützen die folgenden Rollen:
system– Systemanweisungen oder Kontextuser– Benutzernachrichtenassistant– Antworten des LLMstool– Ergebnisse von Tool-Ausführungen
Hinzufügen von Konversationsdaten über die UI¶
- Öffnen Sie Ihre Collection.
- Klicken Sie auf "Variable hinzufügen".
- Fügen Sie für die Konversations-Spalte einen gültigen Wert ein.
- Optionalerweise, füllen Sie andere Spalten aus (z. B. Szenariobeschreibung).
- Klicken Sie auf den Haken rechts zum Speichern.
Massenimport via Datei-Upload¶
Bereiten Sie eine JSONL-Datei vor, in der jeder Wert der Konversations-Spalte dem UCE Format folgt:
{"conversation": {"schema_version": "elluminate.uce/1", "input": {"messages": [...]}}, "scenario": "password_reset", "category": "account"}
{"conversation": {"schema_version": "elluminate.uce/1", "input": {"messages": [...]}}, "scenario": "billing_inquiry", "category": "support"}
Laden Sie diese dann wie folgt hoch:
- Auf der Collections Seite die Collection öffnen.
- Klicken Sie auf "Variablen hochladen" und wählen Sie die JSONL-Datei aus.
- Bestätigen Sie den Upload.
Verwendung von Konversationen in Experimenten¶
Konversationen funktionieren sowohl mit als auch ohne Prompt Templates. Das Template liefert den anfänglichen Kontext und die Konversation liefert den Gesprächsverlauf.
Erweiterte Funktionen¶
Kombination mit anderen Spalten¶
Sie können Conversation-Spalten mit regulären Textspalten mischen, um Metadaten hinzuzufügen:
Tool Calling in Konversationen¶
Übergeben Sie im SDK tools= und tool_choice= an UCEPayloadV1.from_openai(...), genau wie in einem OpenAI Chat-Completions-Request (siehe SDK-Beispiel 3). Das gespeicherte Envelope sieht so aus:
{
"schema_version": "elluminate.uce/1",
"input": {
"messages": [
{"role": "user", "content": "Prüfe meinen Kontostand."}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_account_balance",
"description": "Retrieves the current account balance",
"parameters": {
"type": "object",
"properties": {
"account_id": {"type": "string"}
},
"required": ["account_id"]
}
}
}
],
"tool_choice": "auto"
}
}
Zusammenführen von Tools (Merging)¶
Wenn sowohl Ihr Template als auch Ihre Konversation Tools definieren, werden diese standardmäßig zusammengeführt. Steuern Sie dies über merge_mode in metadata (übergeben Sie metadata= an from_openai):
{
"schema_version": "elluminate.uce/1",
"input": {
"messages": [...],
"tools": [
// Nur diese Tools werden verfügbar sein
],
"metadata": {
"merge_mode": {
"tools": "replace" // Oder alle Tools mit "merge" (Standard)
}
}
}
}
Steuerung des Response-Formats¶
Geben Sie das Ausgabeformat pro Konversation mit einem JSON-Schema an (übergeben Sie response_format= an from_openai, das ein OpenAI response_format-Dict akzeptiert). Das gespeicherte Envelope sieht so aus:
{
"schema_version": "elluminate.uce/1",
"input": {
"messages": [...],
"response_format": {
"json_schema": {
"type": "object",
"properties": {
"issue": {
"type": "string"
},
"priority": {
"type": "string",
"enum": ["low", "medium"]
}
},
"required": ["issue", "priority"]
}
}
}
}
Praxisnahe SDK-Beispiele¶
Beispiel 1: Kundensupport-Chatbot¶
Collection mit Conversation-Spalte erstellen:
from elluminate import Client
from elluminate.schemas import CollectionColumn, ColumnTypeEnum, RatingMode, UCEPayloadV1
client = Client()
# Create collection with conversation column
collection, _ = client.get_or_create_collection(
name="Customer Support Scenarios",
defaults={
"columns": [
CollectionColumn(
name="conversation",
column_type=ColumnTypeEnum.CONVERSATION,
column_position=0,
),
CollectionColumn(
name="scenario_type",
column_type=ColumnTypeEnum.CATEGORY,
column_position=1,
),
]
},
)
Konversationsdaten hinzufügen:
Erstellen Sie das Payload aus OpenAI Chat-Nachrichten mit UCEPayloadV1.from_openai(...).to_uce_dict() und fügen Sie es über collection.add_many([...]) zur Conversation-Spalte hinzu:
# Build a password reset conversation from OpenAI chat messages. The converter
# validates the messages and wraps them in the UCE envelope for you.
password_reset_conversation = UCEPayloadV1.from_openai(
messages=[
{"role": "user", "content": "I can't log into my account."},
{
"role": "assistant",
"content": "I can help you with that. Can you tell me your email address?",
},
{"role": "user", "content": "It's [email protected]"},
{
"role": "assistant",
"content": "Thank you. I've found your account. Would you like me to send a password reset link?",
},
{"role": "user", "content": "Yes please."},
]
).to_uce_dict()
collection.add_many(
variables=[
{
"conversation": password_reset_conversation,
"scenario_type": "password_reset",
}
],
)
Evaluierungskriterien einrichten:
# Create evaluation criteria for conversation quality
criteria = [
"Does the assistant maintain a professional and helpful tone throughout?",
"Does the assistant successfully guide the user to resolve their issue?",
"Does the assistant ask appropriate follow-up questions?",
]
criterion_set, _ = client.get_or_create_criterion_set(
name="Customer Support Quality",
defaults={"criteria": criteria},
)
Experiment ausführen:
# Create and run the experiment
experiment = client.run_experiment(
name="Support Conversation Quality",
prompt_template=None, # No prompt template needed with conversations
collection=collection,
criterion_set=criterion_set,
description="Evaluating customer support conversation quality",
rating_mode=RatingMode.FAST,
llm_config=llm_config,
)
Beispiel 2: Technischer Support über mehrere Runden¶
# Technical troubleshooting conversation with more turns
tech_support_conversation = UCEPayloadV1.from_openai(
messages=[
{"role": "user", "content": "My app keeps crashing."},
{"role": "assistant", "content": "I'm sorry to hear that. What device are you using?"},
{"role": "user", "content": "iPhone 14 with iOS 17."},
{
"role": "assistant",
"content": "Thank you. Have you tried updating the app to the latest version?",
},
{"role": "user", "content": "Yes, it's already updated."},
{
"role": "assistant",
"content": "Let's try clearing the app cache. Go to Settings > Apps > [App Name] > Clear Cache.",
},
{"role": "user", "content": "Okay, I did that. Now what?"},
]
).to_uce_dict()
collection.add_many(
variables=[
{
"conversation": tech_support_conversation,
"scenario_type": "technical_troubleshooting",
}
],
)
Beispiel 3: Tool Calling in Konversationen¶
# Conversation with tool calling: tools and tool_choice pass through the
# converter exactly as in an OpenAI chat-completions request.
tool_calling_conversation = UCEPayloadV1.from_openai(
messages=[{"role": "user", "content": "Check my account balance."}],
tools=[
{
"type": "function",
"function": {
"name": "get_account_balance",
"description": "Retrieves the current account balance",
"parameters": {
"type": "object",
"properties": {"account_id": {"type": "string"}},
"required": ["account_id"],
"additionalProperties": False,
},
},
}
],
tool_choice="auto",
).to_uce_dict()
collection.add_many(
variables=[
{
"conversation": tool_calling_conversation,
"scenario_type": "account_inquiry",
}
],
)
Beste Praktiken¶
Strukturierung von Konversationsdaten¶
Halten Sie Konversationen fokussiert
- Jede Konversation sollte ein spezifisches Szenario oder einen Anwendungsfall testen.
- Beschränken Sie die Länge der Konversation auf den relevanten Kontext (typischerweise 3–10 Nachrichten).
- Entfernen Sie irrelevanten Smalltalk oder Begrüßungen, außer wenn diese spezifisch getestet werden sollen.
Verwenden Sie realistische Gesprächsmuster
- Fügen Sie typische Benutzernachrichten hinzu (Tippfehler, unvollständige Sätze, unterschiedliche Formulierungen).
- Fügen Sie Assistentenantworten hinzu, die das tatsächliche Verhalten Ihres Systems widerspiegeln.
- Beziehen Sie Randfälle ein (unklare Anfragen, Fragen außerhalb des Themas).
Balancieren Sie Ihre Testszenarien
- Happy Paths (60–70 %) – Normale Konversationen, die gut funktionieren sollten.
- Edge Cases (20–30 %) – Ungewöhnliche, aber gültige Gesprächsverläufe.
- Adversarial Cases (10–20 %) – Versuche, das System zu verwirren oder zu stören.
Evaluierungsstrategie¶
Entwerfen Sie konversationsbewusste Kriterien
Gute Kriterien beziehen sich auf den Gesprächsverlauf:
- ✅ "Bleibt der Assistent konsistent mit den vorher in der Konversation gegebenen Informationen?"
- ✅ "Antwortet der Assistent angemessen im Rahmen der Konversation auf die Folgefrage des Nutzers?"
- ❌ "Ist die Antwort hilfreich?" (zu allgemein)
Testen Sie den inkrementellen Aufbau von Konversationen
Anstatt einer langen Konversation sollten Sie die Progression testen:
- Konversation 1: Anfängliche Anfrage
- Konversation 2: Anfängliche Anfrage + eine Folgefrage
- Konversation 3: Anfängliche Anfrage + zwei Folgefragen
Dies hilft zu isolieren, wo das Kontextbewusstsein zusammenbricht.
FAQ¶
Kann ich das Konversationsformat nach dem Hinzufügen bearbeiten?¶
Ja, klicken Sie auf das Bearbeitungssymbol in der Variablen-Tabellenzeile. Achten Sie darauf, eine gültige JSON-Struktur beizubehalten.
Was passiert, wenn mein Konversationsformat ungültig ist?¶
elluminate validiert das Format beim Speichern. Sie sehen eine Fehlermeldung, die angibt, was falsch ist (z. B. "Missing required field 'messages'", "Invalid tool definition").
Kann ich Konversationen mit Batch-Verarbeitung verwenden?¶
Ja, Konversationen funktionieren mit allen Experiment-Funktionen, einschließlich Batch-Operationen und asynchronen SDK-Methoden.
Wie unterscheiden sich Konversationen von Direkten Eingabe-Spalten?¶
- Konversationen: Strukturierte Nachrichtenverläufe mit optionalen Tools/Metadaten. Können mit Templates kombiniert werden.
- Direkte Eingabe: Einzelne Benutzernachricht. Kann optional mit einem Prompt Template kombiniert werden — das Template wird zuerst gerendert (typischerweise ein System-Prompt) und die Direkte Eingabe wird als abschließende User-Nachricht angehängt.
Kann ich mehrere Konversations-Spalten haben?¶
Nein, nur eine Konversations-Spalte pro Collection. Dies sorgt für Klarheit darüber, welche Eingabe den Konversationskontext liefert.
Zählen Konversationsnachrichten zu den Token-Limits?¶
Ja, alle Nachrichten (Template + Konversation) werden an das LLM gesendet und zählen zum Kontextfenster des Modells.
Kann ich in Kriterien auf Konversationsdaten verweisen?¶
Das Rating Model sieht bei der Evaluierung die gesamte Konversation, sodass sich Ihre Kriterien auf "früher in der Konversation" oder "den Gesprächsverlauf" beziehen können.