LangChain.js 接 TypeSafe：0.0.1 包怎么用

小土豆技术创作者 2026-09-22 10 阅读

先说结论

@langchain/typesafe 是 LangChain 官方发布的 npm 包，最新版本 0.0.1，官方描述为 “TypeSafe System One integration for LangChain.js (Jev classifier).”。
0.0.1 属于早期版本，API 很可能变动，生产使用前应锁定版本并关注上游更新。
官方包和自建适配器的主要权衡：官方包省掉类型定义和 LangChain 组件适配；自建适配器更可控，尤其是 state 组装、阈值路由、重试逻辑和业务兜底。
接入骨架可以拆成四步：模型初始化 → 构造结构化判定请求 → 解析类型化输出 → 按 confidence 分流。后文代码是示意，不是官方示例。

先看 npm registry：基础信息可以核实

我直接打开了 @langchain/typesafe 的 registry 元数据，这些是官方数据：

dist-tags.latest 为 "0.0.1"；
description 原文是 "TypeSafe System One integration for LangChain.js (Jev classifier)."；
author.name 是 "LangChain"；
repository.url 指向 git+ssh://git@github.com/langchain-ai/langchainjs.git；
homepage 指向 https://github.com/langchain-ai/langchainjs/tree/main/libs/providers/langchain-typesafe/；
peerDependencies 要求 @langchain/core 为 ^1.0.0；
engines.node 为 >=20。

从这些字段可以看出，这个包不是社区第三方仿包，而是放在 LangChain 官方仓库 langchainjs 里维护的。包名、版本、描述都可以直接核实。版本号 0.0.1 在语义化版本里通常意味着“还不承诺稳定 API”，这是我对版本号的判断，不是官方声明。

它到底做什么：读 readme 原文

npm registry 的包元数据里带了 readme 文本。官方 readme 开头这样描述 Jev 模型：

TypeSafe’s jev model answers typed questions about unstructured input — no string generation, no parsing, no schema wrangling. It returns calibrated probabilities in 70–500ms, and every question in a single request is evaluated in parallel, so asking ten questions costs barely more than asking one.

这段话我理解成两层意思：第一，它不生成文本，而是对非结构化输入回答类型化问题；第二，它返回校准概率，并且多个问题并行评估。注意，70–500ms 来自官方 readme，属于官方数据/官方宣称，我没有自己测试。

官方 readme 给出的安装命令是：

npm install @langchain/typesafe @langchain/core

下面这段是官方 readme 的示例用法（原样引用）：

import { TypeSafeClassifier } from "@langchain/typesafe";

const classifier = new TypeSafeClassifier({
  questions: {
    department: {
      type: "choice",
      criteria: {
        billing: "Payment and payout issues",
        technical: "Bugs and outages",
        sales: null,
      },
      instructions: "Which team should handle this?",
    },
    urgent: { type: "noul", instructions: "Does this convey urgency?" },
    frustration: {
      type: "score",
      criteria: ["calm", "frustrated", "angry"],
      instructions: "How frustrated is the writer?",
    },
  },
});

const result = await classifier.invoke({
  message: "Help! My payouts have been failing for 3 days.",
  account_tier: "enterprise",
});

result.answers.department; // { type: "choice", choice: "billing", confidence: 0.99, probabilities: {...} }
result.answers.urgent; // { type: "noul", noul: 0.97 }
result.answers.frustration; // { type: "score", score: 1.3, legend: { 0: "calm", ... }, ... }

从这个官方示例可以看到：TypeSafeClassifier 接收一个 questions 对象，返回的 answers 每个字段都有明确类型。choice 返回 choice 和 confidence，noul 返回 noul，score 返回 score 和 legend。官方 readme 还写明 result.model 会返回实际回答的模型版本，而不是发送的 jev-latest 别名。这些能力让包看起来比手写 REST 调用方便：你不必自己维护 zod 类型，也不必自己拼 HTTP body。

底层协议：官方 API 参考

如果你想自己写适配器，最终都会落到 TypeSafe 官方的 evaluation endpoint。官方 API 参考给出了核心端点：

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

官方 API 参考的原句是：

Evaluate a state against a map of typed questions and get back structured answers, one per question.

请求体里最关键的三个字段是：

state：可以是 string、object 或 array，表示你要评估的内容；
model：通常使用 "jev-latest"；
questions：一个 map，每个问题通过 type 区分 choice、noul、score。

官方 API 参考还写明，choice 最多支持 255 个选项，score 至少两个 level、最多接受 10 个 level。这些数字来自官方文档，属于官方数据。

官方 LangChain 包和官方 JS SDK，别搞混

TypeSafe 官方还提供 @typesafe-ai/sdk，这是直接面向 API 的 JavaScript/TypeScript SDK。它的 Quickstart 示例是：

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();
const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this ticket about?", {
      billing: null,
      technical: null,
      other: null,
    }),
  },
});

console.log(response.answers.category.choice);

官方 JS SDK 文档写明，@typesafe-ai/sdk 需要 Node.js 20 或更新版本，并且包内含 ESM、CommonJS 和 TypeScript declarations。

我的判断是：@langchain/typesafe 是 LangChain 生态的集成层，@typesafe-ai/sdk 是 TypeSafe 官方的独立 SDK。如果你已经在 LangChain.js 项目里，前者更顺；如果你没有使用 LangChain，直接用官方 JS SDK 会更轻。

另外提醒一点：官方 JS SDK 站点还包含错误类、RetryPolicy、ModelCard 等模块。这次我抓取到的 官方 JavaScript SDK 文档 片段主要是 Quickstart 内容，没有完整展开这些模块。因此这里只提醒你要去核对，不写具体用法。

接入骨架：四步示意，不是官方示例

下面给一个简化接入骨架。它展示了四个动作：模型初始化、构造请求、解析输出、按 confidence 分流。这个骨架只是工程实践中的一种常见做法，不是官方示例，尤其最后 0.85 的阈值不是官方规定。

// 示意：把 TypeSafe 分类能力接进 LangChain.js 的常见工程拆分
// 注意：不是官方示例；阈值 0.85 只是示例，不构成官方建议
import { TypeSafeClassifier } from "@langchain/typesafe";

const classifier = new TypeSafeClassifier({
  questions: {
    department: {
      type: "choice",
      instructions: "Which team should handle this?",
      criteria: {
        billing: "Payment and payout issues",
        technical: "Bugs and outages",
        sales: "Pricing, upgrades, new accounts",
      },
    },
    urgent: { type: "noul", instructions: "Does this convey urgency?" },
  },
});

const result = await classifier.invoke({
  message: "Help! My payouts have been failing for 3 days.",
  account_tier: "enterprise",
});

const dept = result.answers.department;
if (dept.confidence < 0.85) {
  // 低置信：转人工、重试或记录后降级
} else {
  // 高置信：按 dept.choice 直接路由到业务侧
}

其中 TypeSafeClassifier 和问题字段名来自官方 readme；但程序拆分、阈值和兜底逻辑是我自己的工程做法，不要理解为官方建议。

我的判断与清单

以下判断基于前面的官方资料和我的工程经验，属于自己推算/判断，不是官方推荐。

优先用 @langchain/typesafe 的场景：

你已经在使用 LangChain.js，想把 TypeSafe 作为 LangChain 调用链中的一步。
你不想自己维护 zod 类型、问题定义和 LangChain 组件适配。
你愿意接受 0.0.1 的 API 变动，并锁定版本和做基础测试。

优先用官方 @typesafe-ai/sdk 的场景：

你没有用 LangChain.js，不希望为了一个分类器引入 LangChain core。
你需要官方 SDK 提供的错误类、RetryPolicy、ModelCard 等能力。
你想依赖 SDK 的 type inference，直接从 questions 推导出 answer 类型。

适合自建适配器的场景：

你的业务 state 组装、阈值路由、缓存、审计日志和官方包的默认封装不一致。
你需要完全控制请求和错误处理，不想被集成层黑盒化。
你只是想复用官方 HTTP endpoint，而不希望引入额外的类库。

这次没核实的

我没有实际安装运行 @langchain/typesafe，文中官方示例和示意代码都是纸面验证，没有跑过真实 API。
官方 JavaScript SDK 文档中“错误类、RetryPolicy、ModelCard”等模块，我这次只抓到 Quickstart 部分，未打开完整页面核实具体 API 名称和参数，不能给出原文。
TypeSafe 官方宣称的 70–500ms 响应和并行评估，我没有第三方基准数据支撑，只能作为官方数据呈现。
@langchain/typesafe 包内部是否包含重试策略或 ModelCard 能力，readme 里没有明确展示，需要读源码或实际测试才能确认。

参考来源

# Agent # 教程

评论区

0 条评论

登录后可评论。