TypeChat

TypeChat 是一个库，它使使用类型构建自然语言界面变得简单。

传统上，构建自然语言界面一直颇具挑战性。这类应用通常依赖复杂的决策树来确定用户意图，并收集执行操作所需的输入。然而，大型语言模型（LLMs）的出现使得这一过程变得更加容易——我们如今可以直接接收用户的自然语言输入，并将其与预定义的意图进行匹配。不过，这也带来了新的挑战：为了安全起见，我们需要对模型的回复加以约束；为了让后续处理更加顺畅，必须以结构化的方式组织模型的响应；同时还要确保模型的回复是有效的。提示工程旨在解决这些问题，但其学习曲线较为陡峭，且随着提示规模的增大，系统的脆弱性也会显著增加。

TypeChat 用“模式工程”取代了“提示工程”。

你只需定义代表自然语言应用中支持意图的类型即可。这些类型可以很简单，比如用于情感分类的接口；也可以更复杂，例如购物车或音乐应用中的类型。例如，若要向模式中添加更多意图，开发者只需将新的类型加入到联合类型中；而若需构建层级化的模式，则可以通过“元模式”根据用户输入选择一个或多个子模式。

定义好类型后，TypeChat 将负责完成其余工作：

1. 使用类型为 LLM 构建提示。
2. 验证 LLM 的响应是否符合模式要求。如果验证失败，则通过进一步的模型交互修复不符合规范的输出。
3. 在不借助 LLM 的情况下，简洁地总结实例内容，并确认其与用户意图一致。

你只需要类型就够了！

开始使用

安装适用于 TypeScript/JavaScript 的 TypeChat：

npm install typechat

你也可以从源代码入手，使用 TypeChat 来开发：

• Python
• TypeScript
• C#/.NET

要体验 TypeChat 的实际效果，我们建议你探索 TypeChat 示例项目。你可以直接在本地运行这些示例，也可以在 GitHub Codespace 中尝试。

如需了解更多关于 TypeChat 的信息，请访问 文档，其中包含有关 TypeChat 的详细说明以及入门指南。

参与贡献

本项目欢迎各类贡献和建议。大多数贡献都需要您签署一份贡献者许可协议（CLA），声明您有权并将您的贡献权利授予我们。有关详情，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地标记您的 PR（例如添加状态检查或评论）。您只需按照机器人提供的指示操作即可。对于所有使用我们 CLA 协议的仓库，您只需完成一次此步骤。

本项目已采纳 微软开源行为准则。如需更多信息，请参阅 行为准则常见问题解答 或发送邮件至 opencode@microsoft.com 咨询更多问题或提出意见。

商标

本项目可能包含与项目、产品或服务相关的商标或标识。未经授权使用微软商标或标识的行为须遵守并遵循 微软商标与品牌指南。在本项目的修改版本中使用微软商标或标识时，不得造成混淆或暗示微软的赞助关系。任何第三方商标或标识的使用均应遵守该第三方的相关政策。

TypeChat 快速上手指南

TypeChat 是一个利用类型系统（Types）构建自然语言接口的库。它用“模式工程（Schema Engineering）”取代了传统的“提示词工程（Prompt Engineering）”，让开发者只需定义 TypeScript 接口或类，即可轻松实现意图识别、数据验证和自动修复功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows, macOS 或 Linux
• 运行时环境：
  • Node.js (推荐 v16 或更高版本)
  • npm 或 yarn 包管理器
• 大模型访问权限：您需要拥有一个可用的 LLM API Key（如 Azure OpenAI Service 或 OpenAI API），并在代码中配置环境变量。

注意：虽然 TypeChat 核心基于 TypeScript，但也支持 Python 和 .NET。本指南以最常用的 TypeScript/JavaScript 环境为例。

安装步骤

使用 npm 安装 TypeChat 核心库：

npm install typechat

如果您希望从源码运行示例或进行深度定制，可以克隆官方仓库并查看对应语言的子目录：

• TypeScript: ./typescript
• Python: ./python
• .NET: TypeChat.net

基本使用

TypeChat 的核心工作流是：定义类型 -> 创建翻译器 -> 获取结构化结果。

以下是一个最简单的示例，演示如何定义一个“数学计算器”的意图类型，并让用户通过自然语言生成符合该类型的操作指令。

1. 定义类型 (Schema)

首先，定义代表您应用意图的 TypeScript 接口。

// 定义支持的运算类型
type MathOp = "add" | "subtract" | "multiply" | "divide";

// 定义计算请求的结构
interface MathRequest {
    op: MathOp;
    operands: number[];
}

2. 初始化 TypeChat 并发送请求

使用 createLanguageModel 创建模型实例，然后使用 createTranslator 将上述类型绑定到模型。

import { createLanguageModel, createTranslator } from "typechat";
import { MathRequest } from "./types"; // 假设类型定义在此文件中

// 1. 创建语言模型实例 (需设置过程变量 AZURE_OPENAI_API_KEY 或 OPENAI_API_KEY)
const model = createLanguageModel(process.env);

// 2. 创建翻译器，传入类型泛型
const translator = createTranslator<MathRequest>(model, {
    name: "MathRequest",
    description: "A request to perform a math operation.",
});

// 3. 发送自然语言请求
async function calculate() {
    const result = await translator.translate("把 10 和 5 加起来，然后再乘以 2");

    if (result.success) {
        // result.data 已经是符合 MathRequest 类型的合法对象
        console.log("结构化数据:", result.data);
        // 输出示例: { op: "multiply", operands: [15, 2] } (TypeChat 会自动处理逻辑链)
        
        // 在此处执行实际的业务逻辑
        executeMath(result.data);
    } else {
        console.error("翻译失败:", result.message);
    }
}

function executeMath(request: MathRequest) {
    // 具体的业务实现...
}

calculate();

工作流程说明

1. 构造提示词：TypeChat 自动根据您的 MathRequest 类型生成提示词，告诉 LLM 需要返回什么样的 JSON 结构。
2. 验证与修复：如果 LLM 返回的数据不符合类型定义（例如字段缺失或类型错误），TypeChat 会自动发起第二轮对话让 LLM 修复输出，直到验证通过。
3. 结果确认：最终返回给您的 result.data 保证是符合您定义的 TypeScript 类型的有效对象，无需额外的解析代码。

您可以前往 TypeChat 示例项目 查看更多复杂场景（如购物车、音乐应用等）的实现代码。