Score

Ein Score ist ein System One-Fragetyp, um Inhalt gegen geordnete, beschreibende Stufen zu bewerten. Die Antwort enthält einen score, eine Wahrscheinlichkeit für jede Stufe und die Konfidenz.

Verwende einen Score, wenn die Antwort eine Position auf einem Spektrum ist, das du in Stufen beschreiben kannst. Zum Beispiel, wie schwerwiegend ein Fehler ist, wie zufrieden ein Kunde ist oder wie viel Python-Erfahrung ein Kandidat hat. Wenn die Antwort eine aus einer festen Menge von Optionen ohne Reihenfolge ist, verwende einen Choice. Ist sie Ja oder Nein, verwende einen Noul. Einen Fragetyp wählen vergleicht alle drei.

Eine Score-Antwort ist eine Position entlang deiner Stufen in score, die zwischen zwei Stufen liegen kann. Das Modell gibt außerdem eine Wahrscheinlichkeit für jede Stufe in probabilities und einen confidence-Wert für die Antwort zurück.

Die Zahlen vor jeder Stufe sind Positionen, erklärt unter Stufen.

Anfragestruktur

Der POST-Anfragekörper an die TypeSafe-API hat dieselben drei Felder auf oberster Ebene wie jeder andere Fragetyp: state, den auszuwertenden Inhalt; model; und questions. Jede Score-Frage hat die folgenden Felder:

• type: Immer "score".
• instructions: Die Frage, die das Modell beantwortet. Was es bewertet.
• criteria: Ein geordnetes Array von Stufenbeschreibungen, vom unteren Ende der Skala zum oberen. Sollte mindestens zwei Stufen haben; die API akzeptiert bis zu 10.

Unten steht eine Anfrage, bei der der Zustand ein Fehlerbericht ist und die Frage lautet, wie schwerwiegend der Fehler ist:

{
  "state": "The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.",
  "questions": {
    "bug_severity": {
      "type": "score",
      "instructions": "How severe is the reported issue?",
      "criteria": [
        "Cosmetic; no impact to functionality",
        "Broken or degraded feature, but workaround exists",
        "Blocking issue; no workaround exists"
      ]
    }
  }
}

Du wählst die Frage-ID, in diesem Fall bug_severity. Diese ID wird nicht an das Modell gesendet. Die Antwort wird unter derselben ID zurückgegeben.

Stufen

Jeder Eintrag in criteria ist eine Stufe: ein Punkt auf dem Spektrum der möglichen Antworten, in Worten beschrieben. Die Nummer einer Stufe ist ihre Position im criteria-Array, beginnend bei 0, die drei Einträge oben sind also die Stufen 0, 1 und 2. Die Reihenfolge des Arrays ist die Nummerierung.

Das Modell erhält die Beschreibungen und sonst nichts, und jede Stufe wird für sich gegen den Zustand beurteilt.

Der score in der Antwort ist eine Position auf dem Stufenspektrum. Für eine Skala mit drei Stufen läuft er von 0 bis 2, und er kann zwischen zwei Stufen landen.

Unsere Client-SDKs bieten typisierte Fragen. In Python ist dieselbe Frage ein Score:

from typesafe_sdk import Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.",
        questions={
            "bug_severity": Score(
                instructions="How severe is the reported issue?",
                criteria=[
                    "Cosmetic; no impact to functionality",
                    "Broken or degraded feature, but workaround exists",
                    "Blocking issue; no workaround exists",
                ],
            ),
        },
    )

    print(response.answers["bug_severity"].score)

Verwende die Methode system_one oder den Endpunkt https://api.typesafe.ai/v1/systemone, um ein System One-Modell aufzurufen. Das Feld model wählt, welches Modell die Anfrage bearbeitet. Mit TypeSafe bauen behandelt, wo in deinem Code du es aufrufst.

Verwende eines unserer Client-SDKs oder rufe die TypeSafe-API direkt auf. Wenn ein Coding-Agent die Integration für dich schreibt, installiere zuerst den TypeSafe-Agent-Skill, damit er die Formen von Anfrage und Antwort kennt.

Antwortstruktur

Die Antwort hat einen Eintrag in answers pro Frage, unter den IDs aus der Anfrage. Dies ist die Antwort auf die Beispielanfrage oben:

{
  "model": "jev-1.13.0",
  "answers": {
    "bug_severity": {
      "type": "score",
      "score": 1.43,
      "confidence": 0.35,
      "legend": {
        "0": "Cosmetic; no impact to functionality",
        "1": "Broken or degraded feature, but workaround exists",
        "2": "Blocking issue; no workaround exists"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.57,
        "2": 0.43
      }
    }
  },
  "usage": {
    "input_tokens": 332,
    "output_tokens": 18
  }
}

Jede Score-Antwort hat fünf Werte:

• type: Der Typ der TypeSafe-Frage.
• probabilities: Die Wahrscheinlichkeit jeder Stufe, verschlüsselt nach Stufennummer als Zeichenkette. Die Summe aller Werte ist 1.
• score: Die Position auf dem Zahlenstrahl der Stufen, von 0 bis zur höchsten Stufennummer, hier 2. Sie ist jede Stufennummer multipliziert mit ihrer Wahrscheinlichkeit, aufsummiert: 0 x 0.0 + 1 x 0.57 + 2 x 0.43 = 1.43.
• legend: Jede Stufennummer zurück auf ihre Beschreibung abgebildet.
• confidence: Eine Zahl von 0 bis 1, berechnet daraus, wie probabilities verteilt ist. Ein einzelner Gipfel auf einer Stufe bedeutet hohe Konfidenz. Über mehrere Stufen verteilte Wahrscheinlichkeit bedeutet niedrige Konfidenz.

Ein Score von 1.43 bedeutet, dass das Modell zwischen den Stufen 1 und 2 gespalten ist und zu Stufe 1 neigt. Das passt zum Bericht: Der Export ist kaputt, und der Wechsel zu Chrome ist für die meisten Kunden ein Workaround, aber nicht für die, die nur Safari nutzen. Das Modell legt 0.57 auf „Workaround existiert“ und 0.43 auf „kein Workaround“, und die Konfidenz ist 0.35, weil es gespalten ist.

Mit dem Python-SDK hat ScoreAnswer score, confidence, probabilities und legend als typisierte Felder. Das SDK verschlüsselt probabilities und legend nach ganzzahliger Stufe statt nach Zeichenkette.

Einen Score lesen

Schauen wir, wie sich der Score mit verschiedenen Eingaben ändert. Zum Beispiel mit der Frage und ihren Stufen aus der Anfrage oben:

"How severe is the reported issue?"
  → 0: Cosmetic; no impact to functionality
  → 1: Broken or degraded feature, but workaround exists
  → 2: Blocking issue; no workaround exists

Wir können sehen, wie verschiedene Fehlerberichte den Score ändern:

In diesen Beispielen bedeutet Konfidenz 1.0, dass die zurückgegebene Verteilung ihre ganze Wahrscheinlichkeit auf eine Stufe legt. Das beschreibt die Antwort des Modells, nicht eine Garantie, dass die Antwort korrekt ist.

Der Score ist ein wahrscheinlichkeitsgewichteter Mittelwert der Stufennummern. Im dritten und vierten Beispiel teilt sich die Wahrscheinlichkeit zwischen den Stufen 1 und 2. Mehr Gewicht auf Stufe 2 hebt den Score. Er misst nicht den Anteil der Kunden ohne Workaround.

Verschiedene Verteilungen können denselben Score ergeben. Ein Score von 1.0 kann bedeuten, dass die ganze Wahrscheinlichkeit auf Stufe 1 liegt, oder dass die Hälfte auf Stufe 0 und die Hälfte auf Stufe 2 liegt. Lies probabilities und confidence zusammen mit dem Score, um diese Fälle zu unterscheiden.

Ein gebrochener Score ist eine Position. Du kannst ihn verwenden, um Berichte nach Schweregrad zu ordnen, oder ihn auf die nächste Stufe runden, wenn dein Code ein einzelnes Ergebnis braucht. Unser Cookbook zur Entity-Alignment zeigt ein Beispiel für das Runden auf die nächste Stufe, um eine Entscheidung zu treffen.

Niedrige Konfidenz bei einem Score bedeutet meist eines von drei Dingen. Die Stufen überlappen für diesen Zustand, die Frage misst mehr als eine Sache, oder der Zustand sagt nicht genug, um ihn einzuordnen. Unsere Konfidenz-Dokumentation behandelt, wie du sie in deinem Code verwendest.

Gute Stufen schreiben

Beschreibe Situationen, keine Grade. „Kaputte oder beeinträchtigte Funktion, aber es gibt einen Workaround“ gibt dem Modell etwas, wogegen es den Zustand abgleichen kann. „Mäßig schwerwiegend“ nicht. Konkrete Beschreibungen können dem Modell helfen, Stufen zu unterscheiden. Prüfe die Antworten gegen bekannte Beispiele; höhere Konfidenz allein zeigt nicht, dass eine Beschreibung besser ist.

Jede Stufe wird getrennt ausgewertet. Das Modell sieht die Nummer einer Stufe oder ihre Nachbarn nicht, also bedeutet „schlimmer als die vorige Stufe“ ihm nichts, und Zahlen in den Beschreibungen oder den Anweisungen helfen nicht. Hier ist, was passiert, wenn die Stufen nur Zahlen sind, beim Bericht über den falsch ausgerichteten Button aus der Tabelle oben:

instructions: "Rate severity from 0 to 2, where 2 is worst"
criteria: ["0", "1", "2"]
→ score 0.55, confidence 0.33, probabilities 0: 0.45, 1: 0.55, 2: 0.0

Derselbe Bericht erreicht mit den drei beschreibenden Stufen 0.0 bei Konfidenz 1.0. Mit nur Zahlen hat das Modell nichts zum Abgleichen und teilt die Wahrscheinlichkeit zwischen 0 und 1.

Verwende so viele Stufen, wie du klar unterscheiden kannst, bis zu 10. Drei sind in Ordnung. Füge keine Stufen hinzu, die du nicht klar beschreiben kannst.

Halte jede Score-Frage auf einer Dimension. Wenn eine Beschreibung „pünktlich und klug und erfahren“ sagt, misst die Frage drei Dinge, und eine Eingabe, die bei einem hoch und bei einem anderen niedrig ist, lässt sich nicht einordnen. Die Konfidenz sinkt, und der Score bedeutet weniger. Teile sie in eine Score-Frage pro Sache auf und kombiniere sie im Code, wie der nächste Abschnitt zeigt.

Wenn das obere Ende deiner Skala einen seltenen Extremfall hat, auf den du anders reagieren musst, gib ihm eine eigene Stufe. Eine Stimmungsskala, die bei „sehr wütend“ endet, kann „beleidigend oder bedrohlich“ hinzufügen. Ohne diese Stufe erhalten beide Nachrichten vielleicht einen Score nahe dem oberen Ende. Der Score allein kann sie möglicherweise nicht unterscheiden.

Wenn es gar kein Dazwischen gibt und die Antwort eine aus wenigen diskreten Kategorien ist, verwende stattdessen einen Choice oder teile die Frage in mehrere Noul-Fragen auf. Es ist wichtig, deine Stufen mit deinen eigenen Daten zu testen. Zwei Formulierungen derselben Skala können sich auf deinen Daten unterschiedlich verhalten.

Ein komplexes Urteil in mehrere Score-Fragen aufteilen

Ein komplexes Urteil, eines, das von mehreren Dingen abhängt, teilt man am besten in eine Score-Frage pro Sache auf. Du kannst dann die von TypeSafe zurückgegebenen Scores in deinem Code kombinieren, um das Urteil zu fällen. Manche Score-Fragen können wichtiger sein als andere, gib also jeder Score-Frage ein Gewicht für ihre relative Bedeutung. Die Gewichte sind deine. Wenn das kombinierte Ergebnis nicht dem entspricht, was dein Team entscheiden würde, ändere sie im Code und führe es erneut aus. Sende die Score-Fragen in einer Anfrage. Sie werden parallel ausgewertet. Fragen hinzuzufügen ändert die Antwortzeit kaum und kostet ein paar zusätzliche Frage-Token; siehe Mehrere Fragen zusammen stellen.

Die Anfrage unten ist das Spinner-Ticket aus der Tabelle oben mit etwas mehr Kontext. Sie stellt drei Score-Fragen: wie schwerwiegend der Fehler ist, wie frustriert der Kunde ist und wie viel der Bericht einem Ingenieur an die Hand gibt.

{
  "state": "Export to PDF fails with a spinner that never finishes. Some of our team say CSV export still works for them, others say it fails too. This is the third time I'm writing in and honestly I'm done. Steps: open any report, click Export, choose PDF. Chrome 128 on macOS.",
  "questions": {
    "severity": {
      "type": "score",
      "instructions": "How severe is the reported issue?",
      "criteria": [
        "Cosmetic; no impact to functionality",
        "Broken or degraded feature, but workaround exists",
        "Blocking issue; no workaround exists"
      ]
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language or threatening to leave"
      ]
    },
    "report_quality": {
      "type": "score",
      "instructions": "How much does the report give an engineer to work with?",
      "criteria": [
        "No detail; just says something is broken",
        "Names the feature but no steps or environment",
        "Steps to reproduce or environment, but not both",
        "Steps to reproduce and environment"
      ]
    }
  }
}

Die Antwort von TypeSafe:

{
  "model": "jev-1.13.0",
  "answers": {
    "severity": {
      "type": "score",
      "score": 1.24,
      "confidence": 0.64,
      "legend": {
        "0": "Cosmetic; no impact to functionality",
        "1": "Broken or degraded feature, but workaround exists",
        "2": "Blocking issue; no workaround exists"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.76,
        "2": 0.24
      }
    },
    "frustration": {
      "type": "score",
      "score": 1.28,
      "confidence": 0.58,
      "legend": {
        "0": "Calm, just stating facts",
        "1": "Frustrated but civil",
        "2": "Very angry, strong language or threatening to leave"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.72,
        "2": 0.28
      }
    },
    "report_quality": {
      "type": "score",
      "score": 3.0,
      "confidence": 1.0,
      "legend": {
        "0": "No detail; just says something is broken",
        "1": "Names the feature but no steps or environment",
        "2": "Steps to reproduce or environment, but not both",
        "3": "Steps to reproduce and environment"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.0,
        "2": 0.0,
        "3": 1.0
      }
    }
  },
  "usage": {
    "input_tokens": 468,
    "output_tokens": 43
  }
}

Jede Frage wird für sich gegen das Ticket beantwortet und erhält einen Score:

• severity ist 1.24 bei Konfidenz 0.64. Gleiche Lesart wie das einleitende Beispiel: Der Export ist kaputt, und manche haben einen Workaround.
• frustration ist 1.28 bei Konfidenz 0.58. Die Formulierung ist höflich, aber „drittes Mal“ und „ich bin fertig“ verschieben einen Teil des Scores zum oberen Ende, das Modell teilt also 0.72 und 0.28 zwischen „frustriert, aber höflich“ und „sehr wütend“. Für dieses Ticket überlappen die beiden Stufen, weshalb die Konfidenz mittel ist.
• report_quality ist 3.0 bei Konfidenz 1.0. Die Schritte und die Browserversion sind beide angegeben.

Die drei Skalen haben unterschiedliche Längen, normalisiere also vor dem Kombinieren jeden Score. Eine Skala mit vier Stufen gibt 0 bis 3 zurück und eine mit drei Stufen 0 bis 2, ein Spitzenwert auf der einen ist also größer als ein Spitzenwert auf der anderen. Teile jeden Score durch seine höchste Stufennummer, len(criteria) - 1, um jeden Score auf 0–1 zu bringen. Dann bedeuten die Gewichte, was sie sagen: 0.6 auf severity und 0.3 auf frustration lässt severity doppelt so viel zählen.

Der TypeSafe-Python-SDK-Code unten stellt die drei Fragen, normalisiert jeden Score und kombiniert sie mit einer Beispiel-Prioritätsberechnung:

from typesafe_sdk import Score, TypeSafeClient

TRIAGE_QUESTIONS = {
    "severity": Score(
        instructions="How severe is the reported issue?",
        criteria=[
            "Cosmetic; no impact to functionality",
            "Broken or degraded feature, but workaround exists",
            "Blocking issue; no workaround exists",
        ],
    ),
    "frustration": Score(
        instructions="How frustrated is the customer?",
        criteria=[
            "Calm, just stating facts",
            "Frustrated but civil",
            "Very angry, strong language or threatening to leave",
        ],
    ),
    "report_quality": Score(
        instructions="How much does the report give an engineer to work with?",
        criteria=[
            "No detail; just says something is broken",
            "Names the feature but no steps or environment",
            "Steps to reproduce or environment, but not both",
            "Steps to reproduce and environment",
        ],
    ),
}

def normalized(answers, question_id: str) -> float:
    """Put a score on 0 to 1 by dividing by its top level number."""
    top_level = len(TRIAGE_QUESTIONS[question_id].criteria) - 1
    return answers[question_id].score / top_level

def priority(ticket: str) -> float:
    with TypeSafeClient() as client:
        response = client.system_one(
            state=ticket,
            questions=TRIAGE_QUESTIONS,
        )
    answers = response.answers

    severity = normalized(answers, "severity")
    frustration = normalized(answers, "frustration")
    report_quality = normalized(answers, "report_quality")

    # A detailed report helps an engineer investigate, so it raises priority a little.
    return 0.6 * severity + 0.3 * frustration + 0.1 * report_quality

Für die Beispielantwort oben sind die normalisierten Scores 0.62 für severity, 0.64 für frustration und 1.0 für report quality. Die Priorität ist 0.6 × 0.62 + 0.3 × 0.64 + 0.1 × 1.0 = 0.664, was auf 0.66 gerundet wird.

Die Gewichte liegen in deinem Code, du kannst also genau sehen, wie die Zahl entsteht, und sie ändern, wenn das Ranking nicht dem entspricht, was dein Team tun würde. Wenn du später mehr Score-Fragen brauchst, füge sie zu TRIAGE_QUESTIONS hinzu. Die Anzahl der Anfragen bleibt bei eins. Diese Technik, ein komplexes Urteil in getrennte Scores zu zerlegen und sie dann in deinem Code mit Gewichten zu kombinieren, heißt Muster Zusammengesetzte Bewertung.

Strukturierte Stufenbeschreibungen

Beginne mit einer einfachen Textbeschreibung für jede Stufe. Wenn das Modell bei Eingaben, die du für klar hältst, immer wieder zwischen zwei benachbarten Stufen bewertet, gib jeder Stufe ein Objekt statt einer Zeichenkette, mit einem Feld für das, was die Stufe abdeckt, und einem Feld mit ein paar Beispielsituationen. Verwende auf jeder Stufe dieselben Feldnamen, damit das Modell Gleiches mit Gleichem vergleichen kann.

Die Anfrage unten ist das Spinner-Ticket, das wir früher verwendet haben, aber mit Beispielen auf jeder Stufe:

{
  "state": "Export to PDF fails with a spinner that never finishes. Some of our team say CSV export still works for them, others say it fails too.",
  "questions": {
    "bug_severity": {
      "type": "score",
      "instructions": "How severe is the reported issue?",
      "criteria": [
        {
          "what": "Cosmetic; no impact to functionality",
          "examples": [
            "typo in a label",
            "misaligned icon"
          ]
        },
        {
          "what": "Broken or degraded feature, but workaround exists",
          "examples": [
            "export fails in one browser but works in another"
          ]
        },
        {
          "what": "Blocking issue; no workaround exists",
          "examples": [
            "cannot log in",
            "data loss"
          ]
        }
      ]
    }
  }
}

Die Antwort:

{
  "model": "jev-1.13.0",
  "answers": {
    "bug_severity": {
      "type": "score",
      "score": 1.09,
      "confidence": 0.87,
      "legend": {
        "0": {
          "what": "Cosmetic; no impact to functionality",
          "examples": [
            "typo in a label",
            "misaligned icon"
          ]
        },
        "1": {
          "what": "Broken or degraded feature, but workaround exists",
          "examples": [
            "export fails in one browser but works in another"
          ]
        },
        "2": {
          "what": "Blocking issue; no workaround exists",
          "examples": [
            "cannot log in",
            "data loss"
          ]
        }
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.91,
        "2": 0.09
      }
    }
  },
  "usage": {
    "input_tokens": 379,
    "output_tokens": 18
  }
}

Mit einfachen Zeichenketten erreichte dieses Ticket 1.11 bei einer Konfidenz von 0.84. Mit Beispielen erreicht es 1.09 bei 0.87 Konfidenz, eine kleine Verschiebung, weil die einfachen Zeichenketten es bereits gut eingeordnet haben. Der Effekt ist größer, wenn die einfachen Zeichenketten das Modell gespalten lassen, wie die nächste Tabelle zeigt.

Beispiele lenken das Modell, und sie helfen nur, wenn sie deinen echten Eingaben ähneln. Die Tabelle unten ist der einleitende Safari-Bericht mit drei verschiedenen Gruppen von Stufenobjekten:

In diesem Vergleich konzentriert das passende Beispiel fast die ganze Wahrscheinlichkeit auf einer Stufe. Das unpassende Beispiel liefert dasselbe Ergebnis wie einfache Zeichenketten. Höhere Konfidenz belegt nicht, welche Antwort korrekt ist. Wähle Beispiele mit bekannten erwarteten Stufen und teste die überarbeiteten Beschreibungen an getrennten Eingaben, bevor du sie behältst.