typesafe-ai

使用 TypeSafe 构建

TypeSafe 让 AI 智能单元像编程原语一样可用：这些小型判断可以组合成更强大的能力。System One 模型会返回快速、聚焦的判断，供软件直接使用。Jev 是 TypeSafe 的旗舰产品，也是首个 System One 模型。它能理解自然语言，并返回类型化答案和概率，而不是生成文本或推理解释。工作流由代码掌控；当普通代码需要语义理解时，模型会提供可编程的常识。

阅读最新文档

TypeSafe 最新文档是权威信息来源。请在执行任务时阅读文档。 本指南提供方向；文档则涵盖当前概念、提示词指导、API 契约、SDK 用法、模型、限制和示例。

• 从文档索引开始，查找相关页面和操作指南。请针对性地阅读，不要加载整个网站。
• Mintlify 支持在页面路径后附加 .md 来获取 Markdown，例如如何使用 TypeSafe 构建。 请从索引中的链接继续查找；必要时，将不带扩展名的文档页面链接改为 .md。请根据 https://docs.typesafe.ai 解析相对链接。
• 编写集成前，请阅读当前 API 或所选 SDK 页面，以及与设计相关的问题指导。对于新的工作流，还要查看最接近的操作指南：它通常会展示比通用分类器更好的拆分方式。
• 如果无法访问索引，请使用下方的直接链接或网站导航。如果 Markdown 获取失败，请尝试普通页面。如果无法访问在线文档，请使用可用的本地文档或已安装的 SDK 类型，说明这一限制，并避免臆测依赖版本的信息。

任务	从此处开始，并查阅相关详情
了解编程模型	System One、构建指南
探索可构建的内容	用例地图，然后从索引中查找相关操作指南
准备输入和问题	状态、原语，然后查看所选原语的页面
决定如何处理不确定性	置信度
编写 API 代码	HTTP API、Python SDK 或 JavaScript SDK
更新旧版集成	迁移指南和已安装 SDK 的当前参考文档

找到有用的形式

从用户想要的行为入手：应用会展示、选择、更改或移交什么？再反向梳理所需的判断。将已知规则、计算、精确查找和执行留在代码中。保留用户选择的技术栈和范围；在语义理解有帮助时加入 TypeSafe。

在构思或选择架构时，不要只考虑分类。以下模式可作为起点：围绕用户目标组合基本组件，也可以采用不符合既有方案的思路。

• 路由并填充已知参数。 请求可以选择处理程序及其类型化参数。提前提出有用的分支专属问题，并且只使用相关答案。了解函数调用和推测性扇出。
• 选择，而非生成。 在代码中查找候选值或源文本片段，通过判断选出目标内容，然后复制或规范化。代码也可以将源文本组装成格式化文档或阅读指南。了解值提取和结构恢复。
• 查找并判断证据。 检索候选项，比较它们与查询的相关性，并选择有用的上下文。了解重排序和层次分类。
• 将判断转化为可复用的数据。 一次性为各个维度评分，然后让代码或用户控件调整权重、阈值、排名和视图。有了带标签的结果，这些信号也可以成为经典机器学习特征。了解综合评分和特征发现。
• 验证并升级处理。 根据证据核查具体主张或字段；将不确定或失败的情况交给人工或推理模型处理。了解引用核查和提取级联。
• 响应状态变化。 代码可以保留目标和观察结果，同时由新的判断来指导下一步有界操作。将推断状态与观察到的事实区分开，并在将结果应用于已变化的情况前检查其时效性。

对于开放式请求，提供最符合用户目标的少数几个方向，并推荐一个起点。对于具体请求，选择相关模式并着手构建；头脑风暴不是必须经过的环节。

设计判断

根据答案的含义进行选择，然后阅读相关的原语页面：

需求	原语	重要区别
从一组已定义的选项中选择一个	Choice	选择一个选项；其分布用于比较相互竞争的选项
判断某个条件是否成立	Noul	表示“是”的概率；没有单独的置信度；如果多个标签可能同时适用，则每个标签使用一个
沿描述的维度评定程度	Score	按概率加权的有序等级位置；对于分级排序，使用各项之间可比较的 Score

为每个问题提供足够的相关状态来回答：源文本、身份、关系、政策和当前事实。上下文包含多个部分时，优先使用命名的 JSON 字段。将判断写在指令中，并在标准中定义可能的答案。问题 ID 用于代码，不会发送给模型；请在问题中写出完整含义。使用反引号路径引用嵌套状态，例如 ticket.messages[0].text。

每个问题只询问一个范围明确、含义连贯的判断。拆分可独立使用的维度，但不要破坏需要判断的关系。有限范围内的操作选择或情境解读都是有效问题；原子化不意味着只提取字面事实，也不意味着只能用一句话。简单问题可以使用字符串。如果定义、对比、排除项或示例有助于阐明指令或标准，则使用结构化对象或数组。Score 等级必须描述具体情形，并且能够独立理解。

保留所需的答案选项。如果没有任何选项可能符合，请加入无匹配结果；如果存在与之独立相关的用途，则另设一个存在性判断。对于源值选择，请检查候选项是否覆盖全面：模型无法选择未列出的值。

组合与验证

针对相同状态同时提出彼此独立的问题，包括有用的假设性问题。这些问题会并行运行，且彼此无法看到对方的答案。明确写出每个假设前提；代码会使用适用的答案。只有在需要先前答案来获取证据、构造新状态或确定下一组选项时，才有必要发起第二次请求。额外问题仍会消耗令牌；请测量实际请求预算、成本和端到端延迟。

使用概率和置信度来指导行为，并根据用户数据和可能造成的后果评估阈值。Choice/Score 的置信度概括的是分布集中程度，而非整个工作流的正确性或采取行动的许可。Noul 接近 0.5 表示“是”和“否”的概率相近，而非程度中等。多个可接受的备选项也可能分散概率；低置信度不一定意味着无害的偏好选择无效。忽略未使用分支上的不确定性。

明确写出政策，并让原始判断可重复使用。加权分数适用于可相互补偿的偏好；“任何严重违规”规则需要单独的条件。如果证据和问题含义不变，调整权重或显示筛选条件无需重新运行推理。类型化输出能保证接口格式，不保证内容真实。System One 模型经过训练，可做出经过校准的决策；请在目标领域验证其表现。

测试有代表性的案例及其产生的应用行为。如果出现故障，请检查确切的状态、问题、候选项、答案、组合方式和观察到的结果。区分证据缺失、模型错误、代码错误和服务故障。将示例集中的阈值和演示结果视为待评估的示例，而非通用规则或模型的永久局限。在 Web 应用中将 API 凭据保留在服务器端。