TS-DSPy：使用 TypeScript 构建类型安全的 LLM 应用，告别混沌，拥抱秩序

大型语言模型 (LLM) 具有颠覆性的潜力，然而，将其集成到生产环境中常常令人头疼。你精心编写 prompt，祈祷得到理想结果，然后费力地解析输出。LLM 的响应往往不可预测，JSON 格式经常出错，在 TypeScript 这种类型安全的语言中构建可靠的智能体更像是一场持久战。如果能够像定义 TypeScript 函数签名一样严谨地定义 LLM 交互，如果能构建可测试、可预测、自文档化的复杂、工具型智能体，那将是多么美好？受到斯坦福大学颇具影响力的 DSPy 框架的启发，TS-DSPy 将这种结构化的方法引入 TypeScript 生态系统。它是一个生产就绪的框架，用于构建可靠、类型安全的 LLM 应用，涵盖从简单的文本分类器到复杂的自主智能体。本文将深入探讨为什么需要像 TS-DSPy 这样的框架，它的核心组件如何工作，以及如何使用它来构建强大的 AI 应用。

LLM 应用开发的痛点：为什么需要 TS-DSPy？

使用 LLM 构建应用面临诸多挑战，主要体现在以下几个方面：

不可靠的输出 (Unreliable Outputs)：你期望得到 JSON 格式的响应，但实际得到的却是一个包含前导语、缺少括号，甚至附带道歉信息的字符串。编写健壮的解析器成为一项繁琐且容易出错的任务。
隐式的 Prompt 契约 (Implicit Prompt Contracts)：代码和 LLM 之间的“契约”隐藏在多行字符串 prompt 中。这种契约脆弱、难以版本控制，并且缺乏类型安全。例如，你可能会写一个 prompt 期望 LLM 返回特定格式的日期，但如果 LLM 因为某些原因返回了不同的格式，你的代码就可能崩溃。
复杂的逻辑即 Prompt 链 (Complex Logic is “Prompt Chaining”): 构建多步骤的复杂逻辑常常演变成混乱的 prompt 链，状态在字符串中传递，这使得调试、测试和维护变得异常困难。想象一下一个需要先检索信息、然后进行计算、最后生成报告的 AI 应用，每个步骤都需要一个 prompt，而且这些 prompt 之间高度耦合，任何一个 prompt 的修改都可能影响整个流程。
黑盒推理 (Black Box Reasoning)：当 LLM 做出决策（例如选择使用哪个工具）时，其决策过程通常是一个黑盒。理解它为什么选择特定路径非常困难，这使得调试成为一场噩梦。例如，一个智能体在回答用户问题时，选择了使用一个特定的知识库，但你无法得知它为什么选择了这个知识库而不是另一个，这使得你难以优化智能体的行为。

TS-DSPy 通过引入一种程序化的 LLM 构建方法来解决这些问题，将隐式、模糊的指令转化为显式、类型安全的结构。

TS-DSPy 的核心概念：Signatures 和 Modules

TS-DSPy 基于两个主要概念构建：Signatures 和 Modules。

Signatures：LLM 的类型安全 API

Signature 是 TS-DSPy 的核心。它显式地定义了 LLM 交互的契约——输入什么，输出什么。可以把它想象成 LLM prompt 的 TypeScript 接口。

你可以将 Signature 定义为一个简单的字符串，用于快速完成任务：

// 简单的字符串 Signature
const qa = new Predict("question -> answer");

或者，可以定义带有类型化输出的 Signature：

// 带有类型化输出的 Signature
const analyzer = new Predict("text -> sentiment: string, score: float");

但真正的威力来自于使用基于 Class 的 Signatures。它们提供完整的类型安全、自文档化，并且允许更丰富的定义。

import { Signature, InputField, OutputField } from '@ts-dspy/core';

class SentimentAnalysis extends Signature {
    // 整个任务的描述
    static description = "分析给定文本的情感";@InputField({ description: "要分析情感的文本" })
text!: string;

@OutputField({ description: "情感分类" })
sentiment!: 'positive' | 'negative' | 'neutral';

@OutputField({ description: "0 到 1 之间的置信度评分" })
confidence!: number;

}


使用这个 class，TS-DSPy 会自动完成以下操作：

为 LLM 构建一个详细的、优化的 prompt。
验证来自 LLM 的输出。
将原始文本输出解析为类型化的 TypeScript 对象（{ sentiment: 'positive', confidence: 0.9 }）。
在结果上提供完整的 IntelliSense 和类型检查。

再也不用手动解析 JSON 或者祈祷 LLM 给出正确的结果了。例如，如果 LLM 返回的 confidence 值大于 1 或者小于 0，TS-DSPy 会自动抛出错误，防止无效数据进入你的应用。

Modules：可重用的推理模式

Modules 是预构建的推理模式，它们使用 Signatures 来执行任务。它们封装了与 LLM 交互的逻辑。
- Predict：最简单的 Module。它接受一个 Signature 和输入，并产生定义的输出。它是任何单步任务的主力。
- ChainOfThought：实现了“思维链 (Chain of Thought)”技术。它提示 LLM 在给出最终答案之前“逐步思考”，这显著提高了复杂问题的推理能力。例如，对于一个需要多个步骤才能解决的数学问题，ChainOfThought 可以引导 LLM 先列出解题步骤，然后再给出最终答案。
- RespAct (Reason & Act)：一个强大的智能体 Module，可以使用工具。你为它提供一组函数（工具），它可以推理出应该使用哪个工具，使用正确的输入调用它，观察结果，并重复这个过程直到能够回答用户的问题。

实战案例：使用 TS-DSPy 构建工具型智能体

文章提供了一系列示例脚本，展示了如何使用 TS-DSPy 构建各种 LLM 应用。这里我们重点关注工具型智能体的构建，尤其是 RespAct Module 的使用。

RespAct 允许你定义一系列工具（函数），并为每个工具提供详细的描述。这些描述会被编译到 prompt 中，作为 LLM 选择工具的依据。

例如，我们可以创建一个具备以下工具的智能体：

fetchPrice: 获取股票价格。描述：“检索给定股票代码（例如 AAPL, TSLA, GOOGL, MSFT）的当前股价。可以处理单个或多个以逗号分隔的股票代码。以美元返回价格。当您需要最新的股票市场数据时使用它。”
calculate: 执行数学计算。描述：“执行数学计算，包括算术运算、乘法、加法、减法和除法。可以处理包含数字和基本数学运算的表达式。当您需要计算数值结果、计算总数或执行财务计算时使用它时使用它。”
convertCurrency: 转换货币。描述：“使用当前汇率将货币金额从一种货币转换为另一种货币。输入格式：’金额,起始货币,目标货币’ (例如， ‘100,USD,EUR’) 或 ‘金额从到’ 格式。支持 USD, EUR, GBP, JPY。用于国际金融计算或货币转换。”
getNews: 获取新闻。描述：“检索有关特定主题、公司或股票代码的最新新闻文章和信息。提供一个主题、公司名称或股票代码以获取相关的新闻摘要。当您需要当前事件或市场情绪信息时使用此方法。”

const agent = new RespAct("question -> answer", {
    tools: {
        fetchPrice: {
            description: "Retrieves current stock prices for given ticker symbols (e.g., AAPL, TSLA, GOOGL, MSFT). Can handle single symbols or multiple symbols separated by commas. Returns prices in USD. Use this when you need current stock market data.",
            function: (symbol: string) => {
                // ...
            }
        },
        calculate: {
            description: "Performs mathematical calculations including arithmetic operations, multiplication, addition, subtraction, and division. Can handle expressions with numbers and basic mathematical operations. Use this when you need to compute numerical results, calculate totals, or perform financial calculations.",
            function: (expression: string) => {
                // ...
            }
        },
        convertCurrency: {
            description: "Converts monetary amounts from one currency to another using current exchange rates. Input format: 'amount,fromCurrency,toCurrency' (e.g., '100,USD,EUR') or 'amount from to' format. Supports USD, EUR, GBP, JPY. Use this for international financial calculations or currency conversions.",
            function: (input: string) => {
                // ...
            }
        },
        getNews: {
            description: "Retrieves recent news articles and information about specific topics, companies, or stock symbols. Provide a topic, company name, or stock symbol to get relevant news summaries. When you need current events or market sentiment information use this.",
            function: (topic: string) => {
                // ...
            }
        }
    },
    maxSteps: 12
});

当用户提出一个复杂的问题，例如：“如果我购买 100 股 AAPL 和 50 股 TSLA，我的总投资额是多少美元？也将其转换为欧元，并告诉我关于 Apple 的任何最新消息。”

智能体将执行以下步骤：

推理 (Reason)：LLM 分析用户的问题，确定需要哪些工具来回答问题。
行动 (Act)：LLM 根据工具描述选择合适的工具。例如，它可能会首先选择 fetchPrice 工具来获取 AAPL 和 TSLA 的股价。
观察 (Observe)：TS-DSPy 执行 fetchPrice 函数，并将结果注入回与 LLM 的对话中。
重复步骤 1-3，直到收集到所有必要的信息。例如，它可能会接下来选择 calculate 工具来计算总投资额，然后选择 convertCurrency 工具将总投资额转换为欧元，最后选择 getNews 工具获取 Apple 的最新新闻。
给出答案 (Answer)：LLM 基于收集到的信息构建并给出最终答案。

通过这种方式，TS-DSPy 使得构建复杂、多步骤的智能体变得更加容易和可控。

TS-DSPy 的优势：可靠性、可组合性、可维护性和清晰性

TS-DSPy 为 TypeScript 开发者提供了一种全新的 LLM 构建方式。通过从脆弱的 prompt 调整转向结构化的、程序化的方法，你可以获得以下优势：

可靠性 (Reliability)：类型安全、经过验证的输出，你可以依赖它。TS-DSPy 的类型系统确保 LLM 的输出符合你的预期，从而减少了运行时错误。例如，如果你定义了一个 Signature 期望 LLM 返回一个数字，TS-DSPy 会自动验证 LLM 的输出是否是一个数字，如果不是，则会抛出错误。
可组合性 (Composability)：Modules 可以链接和嵌套以创建复杂的应用程序。你可以将多个 Modules 组合在一起，构建更复杂的推理流程。例如，你可以创建一个 Module 用于数据清洗，另一个 Module 用于数据分析，然后将这两个 Modules 组合在一起，构建一个完整的数据分析管道。
可维护性 (Maintainability)：Signatures 是显式的、自文档化的、易于版本控制的。Signatures 清晰地定义了 LLM 交互的输入和输出，这使得代码更容易理解和维护。此外，Signatures 也可以进行版本控制，这意味着你可以跟踪 LLM 交互的变化，并在需要时回滚到之前的版本。
清晰性 (Clarity)：逻辑在你的 TypeScript 代码中，而不是隐藏在一个巨大的 prompt 字符串中。TS-DSPy 鼓励你将 LLM 交互的逻辑放在 TypeScript 代码中，而不是放在 prompt 中，这使得代码更容易理解、测试和调试。

告别 LLM 的混沌时代，拥抱类型安全的未来

将 LLM 视为不可预测的黑盒的时代即将结束。借助像 TS-DSPy 这样的框架，我们可以开始以与我们期望堆栈的其他部分相同的严谨性、可靠性和类型安全性来设计智能系统。

想象一下构建一个自动化的客户服务机器人，它可以理解客户的问题，检索相关的知识库文章，并生成个性化的回复。使用 TS-DSPy，你可以将这个复杂的过程分解为一系列可组合的 Modules，每个 Module 负责一个特定的任务。例如，你可以创建一个 Module 用于理解客户的问题，另一个 Module 用于检索相关的知识库文章，还有一个 Module 用于生成个性化的回复。通过将这些 Modules 组合在一起，你可以构建一个强大而可靠的客户服务机器人。

更进一步，考虑构建一个自动化的代码生成器，它可以根据用户的自然语言描述生成代码。你可以使用 TS-DSPy 定义一个 Signature，该 Signature 接受用户的自然语言描述作为输入，并返回生成的代码作为输出。然后，你可以使用 LLM 来填充这个 Signature，并生成代码。由于 TS-DSPy 提供了类型安全，你可以确保生成的代码符合你的预期，并且不会包含任何错误。

这些只是 TS-DSPy 能够实现的几个例子。通过提供类型安全、可组合性和可维护性，TS-DSPy 使 LLM 的集成变得更加容易和可控，从而开启了 LLM 应用开发的新时代。

要开始使用，请查看 GitHub 仓库，立即尝试构建你的第一个类型安全的 LLM 应用程序。让我们一起告别 LLM 的混沌时代，拥抱类型安全的未来！

TS-DSPy：使用 TypeScript 构建类型安全的 LLM 应用，告别混沌，拥抱秩序