文档索引
在以下地址获取完整的文档索引：https://docs.typesafe.ai/llms.txt 使用此文件可以在进一步探索之前发现所有可用页面。

Score

Score 是 System One 中用于根据有序、描述性级别对内容进行评分的 question 类型。答案包含一个分数、每个级别的概率以及置信度。

当答案是你可以用步骤描述的光谱上的某个位置时，请使用 Score。例如，Bug 有多严重、客户有多满意，或者候选人有多少 Python 经验。如果答案是一组固定选项且选项间没有顺序，请使用 Choice。如果是是或否，请使用 Noul。选择 Question 类型比较了这三者。

Score 答案是 score 中级别范围上的一个位置，可以落在两个级别之间。模型还会在 probabilities 中返回每个级别的概率，以及答案的 confidence 值。

每个步骤前的数字表示位置，详见级别部分。

请求结构

发往 TypeSafe API 的 POST 请求体具有以下三个顶层字段，与其他任何 question 类型相同：state（待评估的内容）；model；以及 questions。每个 Score question 包含以下字段：

type：始终为 "score"。
instructions：模型回答的问题，即其评级的对象。
criteria：按顺序排列的级别描述数组，从量表的低端到高端。至少需要两个级别；API 最多接受 10 个。

以下是一个请求，其中状态是 Bug 报告，问题是该 Bug 的严重程度：

{
  "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"
      ]
    }
  }
}

由你选择 question id，本例中为 bug_severity。此 id 不会发送给模型。答案将在相同的 id 下返回。

级别

criteria 中的每个条目都是一个级别：可能答案光谱上的一个点，用文字描述。级别的数字是它在 criteria 数组中的位置，从 0 开始，所以上述三个条目分别是级别 0、1 和 2。数组的顺序即为编号。

模型仅接收描述信息，每个级别将根据其与 state 的对应关系独立进行判断。

响应中的 score 是级别光谱上的一个位置。对于三级量表，它的范围从 0 到 2，且可以落在两个级别之间。

我们的客户端 SDK 提供类型化的问题。在 Python 中，相同的问题类型为 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)

使用 system_one 方法或 https://api.typesafe.ai/v1/systemone 端点调用 System One 模型。model 字段用于选择处理请求的模型。如何构建 TypeSafe 应用介绍了在代码中何处进行调用。

使用我们的客户端 SDK 或直接调用 TypeSafe API。如果由编码 agent 为你编写集成代码，请先安装 TypeSafe agent skill，以便它了解请求和响应的格式。

Note

instructions 和 criteria 中的每个级别可以是字符串、对象或数组。从字符串开始。当级别需要描述以及几个示例情况时使用对象。请参阅下方的结构化级别描述和 API 参考。

响应结构

响应的 answers 中每个问题都有一个条目，对应请求中的 ID。这是对上述示例请求的响应：

{
  "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
  }
}

每个 Score 答案包含五个值：

type：TypeSafe 问题的类型。
probabilities：每个级别的概率，以级别编号（字符串形式）为键。所有值之和为 1。
score：级别编号线上的位置，从 0 到最高级别编号（此处为 2）。它是每个级别编号乘以其概率，然后相加：0 x 0.0 + 1 x 0.57 + 2 x 0.43 = 1.43。
legend：每个级别编号映射回其描述。
confidence：根据 probabilities 的分布情况计算出的 0 到 1 之间的数字。单峰表示高置信度。概率分散在多个级别上表示低置信度。

分数 1.43 意味着模型在级别 1 和 2 之间摇摆，偏向级别 1。这与报告相符：导出功能已损坏，切换到 Chrome 是大多数客户的变通办法，但对于仅使用 Safari 的客户则不行。模型将 0.57 的概率赋予“存在变通办法”，将 0.43 的概率赋予“无变通办法”，置信度为 0.35，因为概率分布分散。

在 Python SDK 中，ScoreAnswer 拥有类型化的字段 score、confidence、probabilities 和 legend。SDK 中的 probabilities 和 legend 使用整数级别作为键，而非字符串。

解读 Score

让我们看看分数如何随不同输入而变化。例如，使用上述请求中的 question 及其级别：

"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

我们可以观察不同的 Bug 报告如何影响得分：

			`probabilities`
State	`score`	`confidence`	Level 0	Level 1	Level 2
设置页面上的导出按钮偏移了几个像素。	0.0	1.0	1.0	0.0	0.0
The PDF export button does nothing when clicked. I can still export to CSV and convert it myself, but that takes ages.	1.0	1.0	0.0	1.0	0.0
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.	1.11	0.84	0.0	0.89	0.11
The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.	1.43	0.35	0.0	0.57	0.43
Nobody on our team can log in since this morning. We get a 500 error on every attempt.	2.0	1.0	0.0	0.0	1.0

在这些示例中，置信度 1.0 意味着返回的分布将所有概率集中在一个级别上。这描述的是模型的回答，并不保证答案是正确的。

分数是级别数字的概率加权平均值。在第三和第四个示例中，概率分散在级别 1 和 2 之间。级别 2 上的权重增加会提高分数。它并不衡量没有变通办法的客户比例。

不同的分布可能产生相同的分数。1.0 的分数可能意味着所有概率都在级别 1 上，或者级别 0 和 2 各占一半。请结合阅读 probabilities 和 confidence 以区分这些情况。

分数是一个位置。你可以用它根据严重程度对报告进行排名，或者在代码需要单一结果时将其四舍五入到最近的级别。我们的实体对齐 cookbook 展示了四舍五入到最近级别以做出决策的示例。

Score 的置信度低通常意味着以下三种情况之一：这些级别在该状态下重叠，该 question 测量了多个方面，或者状态信息不足以对其进行定位。我们的 Confidence 文档详细介绍了如何在代码中使用它。

编写良好的级别

描述情境，而非程度。“功能损坏或降级，但存在变通办法”给模型提供了与 state 匹配的依据。“中等严重”则没有。具体的描述可以帮助模型区分级别。用已知示例检查答案；仅靠较高的置信度并不能说明描述更好。

每个级别都是单独评估的。模型看不到级别的编号或其邻居，因此“比前一级别更差”对模型来说毫无意义，描述或指令中的数字也无助益。以下是当级别仅由数字组成时，上述表中错位按钮报告发生的情况：

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

同一报告使用三个描述性级别得分为 0.0，置信度为 1.0。如果只使用数字，模型没有可匹配的内容，会将概率分散在 0 和 1 之间。

使用你能明确区分的尽可能多的级别，最多 10 个。三个级别通常足够了。不要添加无法明确区分的级别。

将每个 Score 问题限制在一个维度内。如果描述说“守时、聪明且有经验”，该问题就在衡量三件事，对于其中一项高而其他一项低的输入就无法归类。这会降低置信度，使分数的意义减弱。将其拆分为每件事一个 Score 问题，然后在代码中合并，如下节所示。

如果你的量表顶端有一个需要采取不同行动的罕见极端情况，请为其分配独立的级别。一个以“非常愤怒”结尾的情感量表可以添加“辱骂或威胁”。如果没有这个级别，两条消息的分数可能都接近顶端。仅凭分数可能无法区分它们。

如果完全没有中间状态，且答案是几个离散类别之一，请改用 Choice，或将问题拆分为几个 Noul 问题。用自己的数据测试你的级别很重要。同一量表的不同措辞在你的数据上可能表现不同。

将复杂的判断拆分为多个 Score question

对于取决于多个因素的复杂判断，最好将其拆分为每个因素一个分数（Score）问题。然后，你可以在代码中组合 TypeSafe 返回的分数来做出判断。某些分数问题可能比其他问题更重要，因此请为每个分数问题赋予权重以反映其相对重要性。权重由你决定。当组合结果与你团队的决策不符时，在代码中调整权重并重新运行请求。在一个请求中发送所有分数问题。它们会并行评估。添加问题几乎不会改变响应时间，且仅增加少量问题 token 成本；详见同时提出多个问题。

下面的请求是上表中的加载旋转器工单，并添加了一些上下文。它提出了三个分数（Score）问题：Bug 有多严重、客户有多沮丧、报告为工程师提供了多少可操作的信息。

{
  "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"
      ]
    }
  }
}

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
  }
}

每个 question 都针对工单独立回答，并得出一个分数：

severity（严重性）得分为 1.24，置信度为 0.64。与开篇示例解读相同：导出功能损坏，但部分用户有变通方法。
frustration（挫败感）得分为 1.28，置信度为 0.58。措辞礼貌，但“第三次了”和“受够了”使分数向高级别偏移，因此模型在“挫败但礼貌”和“非常愤怒”之间分配了 0.72 和 0.28 的概率。对于这个工单，这两个级别存在重叠，因此置信度中等。
report_quality（报告质量）得分为 3.0，置信度为 1.0。步骤和浏览器版本均已说明。

这三个量表的长度不同，因此在合并之前，需要标准化每个分数。四级量表返回 0 到 3，三级量表返回 0 到 2，因此一个是顶级得分比另一个更大。将每个分数除以其最高级别编号 len(criteria) - 1，将所有分数置于 0 到 1 之间。然后权重的含义就如其字面意思：严重性权重为 0.6，挫败感权重为 0.3，使得严重性的权重是挫败感的两倍。

下方的 TypeSafe Python SDK 代码提出了这三个问题，标准化了每个分数，并使用示例优先级计算将它们结合起来：

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

对于上述示例响应，标准化后的分数为：严重性 0.62，挫败感 0.64，报告质量 1.0。优先级为 0.6 × 0.62 + 0.3 × 0.64 + 0.1 × 1.0 = 0.664，四舍五入后为 0.66。

权重存在于你的代码中，因此你可以确切地看到这个数字是如何生成的，并在排名与你团队的操作不符时更改它。如果你以后需要更多 Score 问题，可以将它们添加到 TRIAGE_QUESTIONS 中。请求数量仍为一个。这种将复杂判断分解为单独的 Score 然后在代码中使用权重合并的技术称为复合评分模式。

结构化的级别描述

首先为每个级别提供一个基本的文本描述。当模型在你认为明确的输入上总是在两个相邻级别之间评分时，请为每个级别提供一个对象而不是字符串，包含该级别涵盖内容的字段以及一些示例情况字段。在每个级别上使用相同的字段名，以便模型可以进行同类比较。

下面的请求是我们之前使用的那个加载旋转器工单，但在每个级别上都添加了示例：

{
  "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"
          ]
        }
      ]
    }
  }
}

响应如下：

{
  "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
  }
}

使用普通字符串时，该工单的得分为 1.11，置信度为 0.84。添加示例后，得分变为 1.09，置信度为 0.87，由于普通字符串已经能较好地定位结果，因此变化很小。当普通字符串导致模型陷入分歧时，示例的效果会更显著，如下表所示。

示例引导模型，且只有在它们看起来像你的真实输入时才有用。下表展示了带有三组不同级别对象的初始 Safari 报告：

级别描述	`score`	`confidence`
普通字符串：没有包含示例的对象	1.43	0.35
添加了包含有用示例的数组："在某个浏览器中导出失败，但在另一个浏览器中工作正常"	1.03	0.96
添加了与浏览器无关示例的数组："搜索失败，但浏览类别仍然有效"	1.43	0.35

在此对比中，匹配的示例将绝大部分概率集中在一个级别上。不相关的示例返回的结果与纯字符串相同。较高的置信度并不能确定哪个答案是正确的。请选择具有已知预期级别的示例，然后在保留这些描述之前，使用单独的输入测试修订后的描述。