Jev-AI-API-Tutorial: Erstellen Sie Ihre erste strukturierte Entscheidung mit Choice, Score und Noul

Wenn Sie das Modell bereits im Jev-AI-Playground ausprobiert haben, besteht der nächste Schritt meist darin, ein konkretes Urteil in einen serverseitigen Ablauf einzubinden: Ein Ticket oder eine Nachricht empfangen, die von Ihrem Produkt benötigten Fragen festlegen, Wahrscheinlichkeiten und Konfidenz auslesen und den Code über Weiterleitung, Warteschlange oder menschliche Prüfung entscheiden lassen.

Bei der Jev-AI-API geht es nicht in erster Linie um eine Chat-Anfrage. Ihr Kernmodell besteht aus drei klaren Eingaben: State, Model und Questions. State beschreibt den Kontext, Questions beschreiben die Bewertungen, und die Antwort liefert typisierte Ergebnisse anhand der Fragen-IDs. So können Sie KI-Urteile in bestehende Funktionen, Warteschlangen und Agentenabläufe integrieren, statt eine weitere Chat-Oberfläche hinzuzufügen.

Dieses Tutorial behandelt das Anfrageformat, die Wahl zwischen Choice, Score und Noul, eine minimale curl-Anfrage, die Verarbeitung der Antwort, den Kontrollfluss, Fehlergrenzen und eine Produktions-Checkliste.

Ziel des Tutorials: Ein Urteil mit geringem Risiko zu einem Support-Ticket erstellen und den Server entscheiden lassen, ob es automatisch weitergeleitet oder zur menschlichen Prüfung vorgelegt wird.

Inhaltsverzeichnis

• Das Jev-Anfragemodell verstehen
• State: Kontext bereitstellen
• Questions: Choice, Score oder Noul wählen
• Ihre erste Jev-API-Anfrage senden
• Die Antwort lesen und verarbeiten
• Das Ergebnis mit Anwendungslogik verbinden
• Produktions-Checkliste
• Häufig gestellte Fragen

Das Jev-Anfragemodell verstehen

Bild: State liefert den Kontext, Questions beschreiben das Urteil, und das strukturierte Ergebnis geht an Ihren Dienst zurück.

Die Grundidee lässt sich so darstellen:

state + model + questions
            ↓
typed answers + probabilities + confidence
            ↓
your application logic

Die aktuelle Website-Dokumentation nennt POST https://thejevai.com/v1/systemone als Produktions-Endpunkt. Eine Anfrage hat drei zentrale Felder:

• state: ein String, ein JSON-Objekt oder ein Array aus Texten;
• model: der Modellname, zum Beispiel typesafe/jev-1.13;
• questions: typisierte Fragen, deren Schlüssel stabile IDs aus Ihrer Geschäftslogik sind.

Jev trifft das Urteil. Ihre Anwendung bleibt jedoch für Authentifizierung, Bereinigung der Eingaben, Schwellenwerte, Wiederholungsversuche, Protokollierung und die endgültige Aktion verantwortlich. Das übergeordnete Produktmodell wird in der Jev-AI-Einführung erläutert.

State: Kontext bereitstellen

Für einen einfachen Fall einen String verwenden

Wenn sich jedes Urteil auf eine einzelne Nachricht bezieht, ist ein String der einfachste State:

{
  "state": "The customer has tried to connect Stripe for three days."
}

Das eignet sich für Support-Nachrichten, Warnmeldungen, Formularbeschreibungen, Nutzerfeedback und kurze Tickets.

Ein JSON-Objekt für strukturierten Kontext verwenden

Wenn ein Urteil gleichzeitig ein Ticket, eine Bestellung und eine Richtlinie benötigt, verwenden Sie ein Objekt:

{
  "ticket": {
    "text": "The customer has tried to connect Stripe for three days.",
    "channel": "email"
  },
  "customer": {
    "plan": "pro",
    "days_open": 3
  },
  "policy": {
    "same_day_escalation": true
  }
}

Ein Objekt stellt allen Fragen gemeinsame Fakten zur Verfügung. Das bedeutet aber nicht, dass jedes Systemfeld mitgesendet werden sollte. Geben Sie nur den für das Urteil erforderlichen Kontext an und entfernen Sie Geheimnisse, Zahlungsdaten und unnötige personenbezogene Informationen, bevor die Anfrage Ihren Dienst verlässt.

Ein Array für zusammengehörige Texte verwenden

Mehrere Nachrichten, abgerufene Textausschnitte oder Gesprächszusammenfassungen lassen sich als Textarray darstellen. Jedes Element sollte für das aktuelle Urteil relevant sein. Mischen Sie keine unzusammenhängenden Inhalte in State und erwarten Sie nicht, dass das Modell sie zuverlässig ignoriert.

Die aktuelle Website-Dokumentation führt Texte, JSON-Objekte und Textarrays als unterstützte Eingaben auf. Bilder, Audio und Video sind derzeit keine direkten Eingaben. Verarbeiten Sie sie vorher etwa mit Transkription, OCR oder einem anderen Dienst.

Questions: Choice, Score oder Noul wählen

Bild: Der Fragetyp bestimmt das Antwortformat und wie das Ergebnis in den Kontrollfluss eingeht.

Fragetyp	Geeignet für	Zentrales Ergebnis	Typische Aktion
Choice	Eine Option aus mehreren auswählen	choice, probabilities, confidence	Weiterleitung, Klassifizierung, Modellauswahl
Score	Bewertung anhand einer geordneten Skala	score, legend, probabilities, confidence	Rangfolge, Priorität, SLA
Noul	Prüfen, ob eine Aussage zutrifft	noul (Ja-Wahrscheinlichkeit)	Blockieren, bestätigen, eskalieren

Choice: Klassifizierung und Weiterleitung

Verwenden Sie Choice, wenn sich die Antworten aufzählen lassen: Support-Teams, Inhaltskategorien, Aufgabentypen und Modellstufen. Fügen Sie für unbekannte Fälle other oder none-of-the-above hinzu, statt eine falsche Zuordnung zu erzwingen.

Score: geordnete Bewertung

Verwenden Sie Score für Schweregrad, Zufriedenheit, Dringlichkeit und Risikostufen. Die Stufen sollten von niedrig nach hoch geordnet sein und konkrete Beschreibungen haben. Definieren Sie nicht nur „niedrig, mittel, hoch“, sondern erläutern Sie, welche Geschäftsaktion jede Stufe auslösen soll.

Noul: ein einzelnes Ja/Nein-Urteil

Verwenden Sie Noul, wenn sich die Frage als „Ist diese Aussage wahr?“ formulieren lässt. Beispiele: „Bittet der Kunde ausdrücklich um eine Rückerstattung?“ und „Erfordert dieser Tool-Aufruf eine menschliche Bestätigung?“ Noul liefert eine Ja-Wahrscheinlichkeit und sollte nicht mit einem separaten Konfidenzwert verwechselt werden.

Die TypeSafe-Dokumentation betont atomare Fragen. Teilen Sie eine Frage, die Abteilung, Priorität und Risiko zugleich ermitteln soll, in mehrere Fragen auf und führen Sie die Ergebnisse im Code zusammen.

Ihre erste Jev-API-Anfrage senden

Bild: Prüfen Sie zunächst eine kleine, klar abgegrenzte Anfrage, bevor Sie mehrere Fragen hinzufügen.

Einen API-Schlüssel vorbereiten

Speichern Sie den API-Schlüssel in einer serverseitigen Umgebungsvariable:

export JEV_API_KEY="your-server-side-key"

Legen Sie den echten Schlüssel niemals in Browsercode, ein Client-Bundle, einen öffentlichen Artikel oder ein Git-Repository. Aktuelle Hinweise zur Schlüsselverwaltung finden Sie in der Jev-AI-API-Dokumentation.

Eine minimale Noul-Anfrage senden

Die folgende Anfrage entspricht dem Feldformat, das derzeit in der offiziellen Web-Dokumentation gezeigt wird:

curl -X POST https://thejevai.com/v1/systemone \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "A customer has tried to connect Stripe for three days.",
    "questions": {
      "urgent": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }'

Den Playground zum Prüfen einer Anfrage verwenden

Wenn Sie beim vollständigen JSON-Format für Choice oder Score unsicher sind, definieren Sie eine Frage im Playground, führen Sie sie aus und prüfen Sie die von der Seite angezeigte API-Anfragevorschau. Das ist sicherer, als Feldnamen aus einem veralteten Beispiel zu erraten.

Die Antwort lesen und verarbeiten

Bild: Prüfen Sie Antwort und Schwellenwert, bevor Sie das Ergebnis an eine Automatisierung oder zur Prüfung weitergeben.

Antworten anhand der Fragen-ID auslesen

Die Antwort verwendet die von Ihnen gesendeten Fragen-IDs. Sie kann konzeptionell so aussehen:

{
  "answers": {
    "urgent": {
      "noul": 0.87
    }
  },
  "usage": {
    "input_tokens": 42,
    "output_tokens": 0
  },
  "elapsedMs": 214
}

Dies ist eine beispielhafte Antwort, kein vollständiges API-Schema. Aktuelle Felder, Fehler und Modellversionen finden Sie in der offiziellen API-Referenz.

Wahrscheinlichkeit als Signal, nicht als Urteil behandeln

Legen Sie je nach Risikostufe unterschiedliche Schwellenwerte fest:

• Weiterleitung eines Tickets mit geringem Risiko: urgent > 0.8 kann in eine automatische Warteschlange gelangen.
• Aktionen mit mittlerem Risiko: 0.6–0.8 kann eine Stichprobe oder ein zweites Urteil auslösen.
• Aktionen mit hohem Risiko: Selbst eine hohe Wahrscheinlichkeit sollte weiterhin Autorisierung, feste Regeln und menschliche Bestätigung durchlaufen.

Schwellenwerte sind Teil Ihrer Geschäftsrichtlinie und keine Standardantwort von Jev. Kalibrieren Sie sie anhand historischer Daten und Gegenbeispiele.

Fehler und Zeitüberschreitungen behandeln

Ein produktiver Client sollte Nicht-2xx-Antworten, Zeitüberschreitungen, fehlende Felder, unbekannte Auswahlmöglichkeiten, Modellversionswechsel und doppelte Übermittlungen behandeln. Wiederholungsversuche brauchen eine Idempotenzstrategie: Ein Netzwerkfehler darf weder eine Zahlung wiederholen noch eine Löschung oder Berechtigungsänderung auslösen.

Das Ergebnis mit Anwendungslogik verbinden

Beispiel: Prioritätsablauf für Support-Tickets

result = jev.system_one(
    model="typesafe/jev-1.13",
    state=ticket,
    questions={
        "needs_human": {
            "type": "noul",
            "instructions": "Does this ticket require a human review?"
        }
    },
)

if result.answers["needs_human"].noul >= 0.85:
    queue_for_review(ticket)
else:
    route_automatically(ticket)

Das Beispiel veranschaulicht den Kontrollfluss. Verwenden Sie für die genauen Felder des Python-SDKs, JavaScript-SDKs oder der REST-API die aktuellen offiziellen Dokumente und die im Playground exportierte Anfrage.

Anfragen mit mehreren Fragen bewusst gestalten

Ein State kann mehrere Fragen unterstützen:

• department: Choice für das zuständige Team;
• urgency: Score für die Priorität;
• needs_human: Noul für eine Prüfung.

Jede Frage sollte genau ein Urteil beschreiben. Die Anwendung führt die Ergebnisse zu Aktionen zusammen. Wenn Sie also eine Weiterleitungsrichtlinie ändern, müssen Sie weder die Dringlichkeits- noch die Prüfungsfrage neu schreiben.

Produktions-Checkliste

Prüfen Sie vor dem Start:

1. Der API-Schlüssel ist ausschließlich in serverseitigen Geheimnissen oder einem Umgebungsvariablen-Manager gespeichert.
2. State hat Längenbegrenzungen, Regeln für sensible Daten und Berechtigungsprüfungen.
3. Jede Frage besitzt eine stabile ID, einen definierten Antwortbereich und klare Anweisungen.
4. Der Client prüft den HTTP-Status und das Antwortformat.
5. Wahrscheinlichkeitsschwellen richten sich nach dem Risiko und verwenden nicht einen globalen Einheitswert.
6. Aktionen mit großen Auswirkungen behalten feste Regeln, Autorisierung und menschliche Prüfung bei.
7. Das System protokolliert Modellversion, Fragendefinition, Eingabezusammenfassung und endgültige Aktion.
8. Zeitüberschreitungen, Wiederholungsversuche, Ausweichpfade und menschliche Übernahme sind festgelegt.
9. Chinesisch, Englisch, Fachbegriffe und Grenzfälle sind im Evaluationsdatensatz vertreten.
10. Nutzungs- und Tarifdetails werden anhand der Jev-AI-Preisseite und der aktuellen API-Dokumentation geprüft.

Für Architektur und Modellauswahl lesen Sie weiter mit Jev AI vs. LLMs. Informationen zu Agentenrouting und Sicherheitsvorkehrungen finden Sie unter Jev-AI-Schutzregeln für Agenten.

Häufig gestellte Fragen

Ist die Jev-AI-API ein Chat-Endpunkt?

Nein. Sie nimmt State und typisierte Fragen entgegen und liefert strukturierte Antworten zurück, die eine Anwendung auslesen kann. Sie kann als Urteilsknoten innerhalb eines Chatsystems oder Agenten dienen, ist aber nicht für die Erzeugung von Chat-Absätzen ausgelegt.

Kann eine Anfrage mehrere Fragen enthalten?

Ja. Die Website- und TypeSafe-Dokumentation beschreiben mehrere Fragen, die anhand desselben State ausgewertet werden. Halten Sie jede Frage unabhängig und klar abgegrenzt und versehen Sie sie mit einer stabilen ID.

Ist der Noul-Wert dasselbe wie Konfidenz?

Nein. Noul ist die Wahrscheinlichkeit, dass die Antwort „Ja“ lautet. Choice und Score liefern jeweils eigene Wahrscheinlichkeits- und Konfidenzfelder. Verwenden Sie für das genaue Antwortformat immer die aktuelle API-Dokumentation.

Unterstützt Jev Bilder?

Die aktuelle Website-Dokumentation nennt Texte, JSON-Objekte und Textarrays als State-Eingaben. Bilder, Audio und Video sind derzeit keine direkten Eingaben. Verarbeiten Sie sie zunächst etwa mit OCR, Transkription oder einem anderen Modell.

Woran erkenne ich, ob die API zu meinem Produkt passt?

Beginnen Sie mit einer messbaren Entscheidung mit geringem Risiko und einem klaren Antwortbereich. Prüfen Sie sie im Playground und testen Sie anschließend das Verhalten des Servers anhand historischer Daten und Grenzfälle.

Fazit

Bei einer Jev-AI-Integration kommt es nicht darauf an, nur einen Modellaufruf auszuführen. Entscheidend ist die Trennung von State, Fragen, Ergebnissen und Aktionen. State liefert Fakten, Choice/Score/Noul das Urteil, Wahrscheinlichkeiten machen Unsicherheit sichtbar, und der Anwendungscode bestimmt den endgültigen Schritt.

Wenn diese Kette dokumentiert, getestet und überwacht wird, kann Jev AI sich von einer Playground-Demo zu einer wartbaren Entscheidungskomponente in Ihrem Produkt entwickeln.

Recherche-Datum: 2026-09-20

Primärquellen: Jev-AI-Startseite, Jev-AI-Dokumentation, Jev-AI-Playground, TypeSafe-Einführung