TypeSafe Jev Schritt-für-Schritt-Tutorial. Praxisleitfaden für TypeSafe Jev, das System-One-KI-Modell für typisierte Softwareentscheidungen.
01
Gestalten Sie die Aufgabe
Entscheiden Sie, ob Jev passt
Jev ist kein Chat-Model. Es wandelt den bestehenden Zustand in eine geschlossene Entscheidung „Choice“, „Score“ oder „Noul“ um und gibt eine Wahrscheinlichkeitsverteilung zurück.
Eine gute Passform
Verwenden Sie Jev für begrenzte Entscheidungen
Leiten Sie eine Anfrage an eine benannte Warteschlange weiter.
Platzieren Sie einen Datensatz auf einer geordneten Risiko- oder Qualitätsskala.
Schätzen Sie, ob eine klar formulierte Bedingung wahr ist.
Keine gute Passform
Verwenden Sie stattdessen ein generatives Modell
Offenen Text schreiben, zusammenfassen, übersetzen oder neu schreiben.
Führen Sie ein natürliches Gespräch mit mehreren Gesprächsrunden.
Erstellen Sie eine Antwort, wenn die gültigen Ausgaben nicht im Voraus benannt werden können.
Das offizielle mentale Modell
STATE
Ein Staat zur Bewertung
Übergeben Sie eine Zeichenfolge, ein Objekt oder ein Array, das den Text und die zugehörigen Fakten enthält, die das Urteil benötigt. Verwenden Sie für die meisten echten Anfragen benannte Objektfelder.
QUESTIONS
Ein schnelles Urteil pro Frage
Bei jeder Frage sollte es um eine fokussierte Sache gehen, die eine sachkundige Person anhand der bereitgestellten Informationen schnell beurteilen kann.
PARALLEL
Unabhängige Fragen parallel
Fragen in einer Anfrage sehen denselben Status, werden unabhängig voneinander ausgeführt und geben keine Antwort an eine andere weiter.
CODE
Verfassen Sie Antworten im Code
Gewichtung, Schwellenwert, Verzweigung und Kombination eingegebener Antworten in gewöhnlichem Code, anstatt die Workflow-Logik in einer Eingabeaufforderung zu verbergen.
Zersetzungstest: Wenn das Urteil mehrere unabhängige Faktoren berücksichtigt oder eine ausführliche Begründung erfordert, teilen Sie es in atomare Fragen auf und kombinieren Sie die Antworten im Code.
Nach diesem Kapitel:Sie können Aufgaben zur Inhaltsgenerierung von Aufgaben zur strukturierten Entscheidung trennen.
Verwenden Sie „Choice“ für sich gegenseitig ausschließende Bezeichnungen, „Score“ für geordnete Ebenen und „Noul“ für eine Richtig-oder-Falsch-Beurteilung.
Typ
Sie liefern
Sie erhalten
Verwenden Sie wann
choice
Benannte Optionen → Beschreibungen
Ausgewählter Schlüssel + Wahrscheinlichkeiten pro Option (+ Konfidenz)
Für ungeordnete, feste Alternativen verwenden. Fügen Sie „Andere/Keine“ hinzu, wenn die Liste möglicherweise nicht alle Bundesstaaten abdeckt. Der gewählte Wert ist die Option mit der höchsten Wahrscheinlichkeit.
Die Stufen werden ab 0 indiziert. Der Wert ist der gewichtete Durchschnitt aller Stufenwahrscheinlichkeiten, sodass er zwischen zwei Stufen liegen kann.
Die Wahrscheinlichkeit, dass eine Aussage wahr ist
Für ein klares Ja/Nein-Urteil verwenden. Nahezu 0,5 bedeutet Unsicherheit, kein mittlerer Wert der Immobilie. Noul hat kein separates Vertrauensfeld.
{
"type": "noul",
"noul": 0.95
}
Die Punktzahl ist nicht die Genauigkeit. Eine Punktzahl von 1,5 in einer Rubrik von 0–2 ist ein erwartetes Niveau, nicht „75 % richtig“. Betrachten Sie Score- oder Choice-Konfidenz nicht als Genauigkeitsversprechen.
Nach diesem Kapitel:Sie können die richtige Antwortform für Weiterleitung, Moderation und Risikobewertung auswählen.
Halten Sie Optionsnamen stabil, definieren Sie sich gegenseitig ausschließende Grenzen, schließen Sie einen Restpfad ein und geben Sie jeder Frage eine Entscheidung.
Starke Kriterien schreiben
Disjunkte Optionen. Wenn zwei Auswahlschlüssel beide wahr sein können, bekämpfen die Operatoren das Modell.
Beschreiben Sie Kanten. Sagen Sie, was buy_intent beinhaltet (Lagerbestand, Lieferadresse) im Vergleich zu price_question.
Bewahren Sie den Rest zuletzt auf. Benutzen Sie andere/Menschen als Notluken, nicht faule Allheilmittel.
Bestellwert aufsteigend. Kriterienarrays sind am niedrigsten → am höchsten.
Eine Entscheidung pro Frage. Teilen Sie „Route“ und „Dringlichkeit“ in separate Schlüssel auf.
Anatomie einer Frage
question_id
Ein Antwortsuchschlüssel für Ihren Code. Es wird nicht an das Modell gesendet, daher muss die Anleitung trotzdem die vollständige Frage enthalten.
type
Wahl, Partitur oder Noul. Wählen Sie die Form aus, auf die Ihr Code direkt reagieren kann.
instructions
Das vollständige, konkrete Urteil. Es kann eine Zeichenfolge, ein Objekt oder ein Array sein und auf benannte Zustandspfade verweisen.
criteria
Auswahlmöglichkeiten, geordnete Punktestände oder optionale Richtig/Falsch-Klärung für Noul.
Beispiel · eine Entscheidung, disjunkte Grenzen
route: {
type: 'choice',
instructions: 'Route this ticket to one queue.',
criteria: {
tech: 'Bugs, outages, API failures, or integrations',
sales: 'Pricing, plans, demos, or new-purchase intent',
billing: 'Charges, invoices, receipts, or subscriptions',
human: 'Ambiguous, sensitive, legal, or multi-issue'
}
}
Strukturieren Sie den Status und referenzieren Sie exakte Felder
Bewahren Sie Beweise in benannten Statusfeldern auf und richten Sie mit Punkt-und-Index-Pfaden Anweisungen darauf. Dies verringert die Unklarheit darüber, welcher Text, welcher Datensatz oder welche Richtlinie die Antwort steuern soll.
const state = {
ticket: {
message: 'I was charged twice. Please refund the duplicate.',
orderId: 'A-104'
},
order: { charges: [49, 49] },
refundPolicy: 'Duplicate charges are eligible for a refund.'
};
const questions = {
refund_requested: {
type: 'noul',
instructions: 'Does `ticket.message` request a refund?'
},
policy_supports_refund: {
type: 'noul',
instructions: 'Does `refundPolicy` support the request given `order.charges`?'
}
};
Standardmäßig Batch: Stellen Sie alle Fragen, die denselben Status verwenden, in einer Anfrage – auch spekulative Fragen. Stellen Sie eine zweite Anfrage nur dann, wenn der Status oder die Optionen tatsächlich von einer früheren Antwort abhängen.
Nach diesem Kapitel:Sie können eine stabile, testbare Fragedefinition schreiben, die der Code nutzen kann.
Rufen Sie den offiziellen System One-Endpunkt oder das offizielle SDK von Ihrem Server aus auf, überprüfen Sie die eingegebene Antwort und behandeln Sie Validierungs-, Ratenbegrenzungs- und Überlastungsfehler. Gateway bleibt ein optionaler Zugriffspfad.
Beginnen Sie mit dem offiziellen HTTP-Endpunkt
Behalten Sie TYPESAFE_API_KEY auf dem Server. Senden Sie Status, Modell und eine Karte mit benannten Fragen an POST /v1/systemone.
curl -X POST https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Stripe has failed for 3 days. I am losing sales.",
"model": "jev-latest",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions"
}
},
"is_urgent": {
"type": "noul",
"instructions": "Does this message convey urgency?"
}
}
}'
Verwenden Sie das offizielle SDK für getippte Antworten und Wiederholungsversuche
Das Python SDK liest TYPESAFE_API_KEY aus der Umgebung, verwendet standardmäßig jev-latest, stellt typisierte Frage-/Antwortklassen bereit und wendet seine standardmäßige Wiederholungsrichtlinie an.
pip install typesafe-sdk
from typesafe_sdk import Choice, Noul, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state={"message": "Stripe has failed for 3 days.", "impact": "Losing sales"},
questions={
"department": Choice(
instructions="Which team should handle this?",
criteria={
"billing": "Payment or subscription issues",
"technical": "Bugs or integration problems",
"sales": "Pricing or account questions",
},
),
"is_urgent": Noul(
instructions="Does `message` and `impact` convey urgency?"
),
},
)
department = response.answers["department"]
print(department.choice, department.confidence)
print(response.answers["is_urgent"].noul)
Fehlender oder ungültiger API-Schlüssel. Überprüfen Sie den Inhabertoken.
422
Ungültige Anforderungsform. Überprüfen Sie die Antwort auf das fehlerhafte Feld.
429
Ratenlimit überschritten. Machen Sie einen Schritt zurück, bevor Sie es erneut versuchen.
529
Dienst vorübergehend überlastet. Machen Sie einen Schritt zurück, bevor Sie es erneut versuchen.
Verwenden Sie für 429 und 529 einen exponentiellen Backoff anstelle eines sofortigen Wiederholungsversuchs. Die offiziellen SDKs führen dies automatisch im Rahmen ihrer Standard-Wiederholungsrichtlinie durch.
Alternative: Vercel AI Gateway
Diese Site dokumentiert auch Gateway als Zugriffsschicht für die AI SDK-Auswertung. Es handelt sich um einen alternativen Integrationspfad, der nicht Teil von Jev oder TypeSafe ist.
import { experimental_evaluate as evaluate } from 'ai';
import { gateway } from '@ai-sdk/gateway';
const result = await evaluate({
model: gateway('typesafe-ai/jev'),
state,
questions,
});
Nach diesem Kapitel:Sie können die Anmeldeinformationen serverseitig behalten und getippte Antworten mit Wahrscheinlichkeiten erhalten.
Verwandeln Sie die höchste Wahrscheinlichkeit nicht direkt in eine endgültige Aktion. Legen Sie basierend auf dem Geschäftsrisiko Bereiche für Vorschläge, Bestätigungen und menschliche Überprüfungen fest.
PROBABILITY
Beweise für jede Option oder Ebene
Choice und Score geben die vollständige Verteilung zurück. Verwenden Sie es, wenn zweitplatzierte Optionen, Unklarheiten oder benutzerdefinierte Unsicherheitsmaße wichtig sind.
CONFIDENCE
Eine Zusammenfassung der Verteilungsform
Das Vertrauen komprimiert, wie konzentriert oder flach die Verteilung ist, auf 0–1. Sie ist nicht identisch mit der gewählten Optionswahrscheinlichkeit.
Noul: Noul gibt bereits P(true) zurück, daher hat es keine separate Konfidenz. Werte nahe 0,5 sind unsicher; Schwellenwert sowohl für die Ja- als auch für die Nein-Seite je nach Risiko.
TypeSafe legt Vertrauen in der Optionsverteilung offen. Eine praktische Richtlinie ist:
01
Hohes Selbstvertrauen
Schlagen Sie die Auswahl (Tag, Route oder Urteil) automatisch in Ihrer Benutzeroberfläche vor.
02
Mittleres Selbstvertrauen
Zeigen Sie den Vorschlag an, fordern Sie jedoch eine Bestätigung durch einen Bediener auf, bevor Sie fortfahren.
03
Geringes Vertrauen
Ohne Standardaktion an eine menschliche Warteschlange senden.
Kalibrieren Sie Grenzwerte für gekennzeichnete Beispiele aus Ihrem Stream oder Posteingang. Schwellenwerte sind anwendungsfallspezifisch. Überweisen Sie Vorschläge niemals in Geld oder erstatten Sie Nebenwirkungen.
Legen Sie einen globalen Schwellenwert für die Aktion fest, nicht für das Modell
action = response.answers["action"]
if action.confidence < 0.5:
route_to_human(state) # uncertain: do not guess
elif action.choice == "check_balance":
show_balance(account_id) # reversible, low stakes
elif action.choice == "approve_transfer":
if action.confidence > 0.9:
confirm_then_execute(account_id)
else:
ask_user_to_confirm(account_id) # higher stakes, higher bar
Vor der Automatisierung kalibrieren
Sammeln Sie repräsentative, beschriftete Beispiele aus dem realen Arbeitsablauf.
Zeichnen Sie Antworten, Verteilungen, Konfidenz, Latenz und die menschliche Entscheidung auf.
Wählen Sie die Schwellenwerte für reversible, kostspielige und irreversible Aktionen separat aus.
Überwachen Sie die Abweichung und bewerten Sie sie erneut, nachdem sich Status, Anweisungen, Kriterien oder Modellalias geändert haben.
Staatstipps
Übergeben Sie eine Zeichenfolge, ein Objekt oder ein Array als Status. Bevorzugen Sie strukturierte Datensätze (Kommentartext + Metadaten) gegenüber dem Ablegen eines gesamten Chat-Protokolls, wenn nur eine Nachricht wichtig ist.
Nach diesem Kapitel:Sie können einen Fallback mit geringer Konfidenz entwerfen und Schwellenwerte mit beschrifteten Daten kalibrieren.
Gehen Sie vom Prototyp zu einer realen Aufgabe über
Erstellen Sie einen vollständigen Workflow mit strukturiertem Status, parallelen Fragen, Code-eigenen Richtlinien, Prüfungsnachweisen, Wiederholungsversuchen und einem menschlichen Fallback.
Erstellen Sie einen vollständigen Support-Triage-Workflow
Senden Sie einen strukturierten Ticketstatus und stellen Sie parallel drei unabhängige Fragen. Behalten Sie die Routing- und Sicherheitsrichtlinien im Code bei.
STATE→CHOICESCORENOUL→POLICY
const questions = {
department: {
type: 'choice',
instructions: 'Which team should handle `ticket.message`?',
criteria: {
returns: 'Exchanges, wrong or damaged items',
shipping: 'Delivery status, delays, or lost packages',
billing: 'Charges, invoices, or payment problems',
other: 'None of the above'
}
},
frustration: {
type: 'score',
instructions: 'How frustrated is the customer?',
criteria: ['Calm', 'Concerned but civil', 'Very angry']
},
refund_requested: {
type: 'noul',
instructions: 'Does `ticket.message` request money back?'
}
};
Verwandeln Sie getippte Antworten in eine überprüfbare Entscheidung
Behalten Sie Anmeldeinformationen und Modellaufrufe serverseitig bei.
Überprüfen Sie die Statusgröße, erforderliche Felder und Fragendefinitionen, bevor Sie die API aufrufen.
Speichern Sie die Modellversion, die Fragenversion, die Wahrscheinlichkeiten, das Vertrauen und die endgültige Aktion.
Geben Sie einen expliziten anderen/menschlichen Weg an und erfinden Sie niemals einen Standardwert für die Unsicherheit.
Wiederholen Sie 429 und 529 mit begrenztem exponentiellem Backoff. Validierungsfehler nicht erneut versuchen.
Testen Sie anhand gekennzeichneter Randfälle und kalibrieren Sie die Schwellenwerte neu, bevor Sie die Automatisierung aktivieren.
Case index
Six Jev patterns to explore next
These are research paths, not claims that this site built the projects. Each card opens the corresponding category in the open-source radar so you can inspect real implementations and source evidence.