Ax - 使用 DSPy 在 TypeScript 中构建可靠的 AI 应用

Ax 将 DSPy 的方法引入 TypeScript——只需描述你想要实现的功能，剩下的工作由框架自动完成。生产就绪、类型安全，兼容所有主流大模型。

问题所在

使用大模型开发应用非常痛苦。你需要编写提示词、测试它们，但往往很快就会失效。一旦更换服务提供商，所有代码都需要重写。再加上验证、错误处理和重试机制，最终你会发现自己的精力都花在维护基础设施上，而不是交付新功能。

解决方案

只需定义输入和输出，其余的一切都交给 Ax 处理。

import { ai, ax } from "@ax-llm/ax";

const llm = ai({ name: "openai", apiKey: process.env.OPENAI_APIKEY });

const classifier = ax(
  'review:string -> sentiment:class "positive, negative, neutral"',
);

const result = await classifier.forward(llm, {
  review: "This product is amazing!",
});

console.log(result.sentiment); // "positive"

无需进行提示工程，也无需反复试验。支持 GPT-4、Claude、Gemini 等任意大模型。

为什么选择 Ax

一次编写，随处运行。 只需一行代码即可在 OpenAI、Anthropic、Google 等超过 15 家服务商之间无缝切换，无需任何修改。

更快地交付。 停止不断调整提示词，只需定义输入和输出，框架会自动生成最优的提示内容。

生产就绪。 内置流式处理、验证、错误处理和可观ability 功能。已在生产环境中稳定运行，日均处理数百万次请求。

越用越智能。 通过示例数据训练你的程序，准确率会自动提升，无需任何机器学习专业知识。

示例

提取结构化数据

const extractor = ax(`
  customerEmail:string, currentDate:datetime -> 
  priority:class "high, normal, low",
  sentiment:class "positive, negative, neutral",
  ticketNumber?:number,
  nextSteps:string[],
  estimatedResponseTime:string
`);

const result = await extractor.forward(llm, {
  customerEmail: "Order #12345 hasn't arrived. Need this resolved immediately!",
  currentDate: new Date(),
});

复杂嵌套对象

import { f, ax } from "@ax-llm/ax";

const productExtractor = f()
  .input("productPage", f.string())
  .output("product", f.object({
    name: f.string(),
    price: f.number(),
    specs: f.object({
      dimensions: f.object({
        width: f.number(),
        height: f.number()
      }),
      materials: f.array(f.string())
    }),
    reviews: f.array(f.object({
      rating: f.number(),
      comment: f.string()
    }))
  }))
  .build();

const generator = ax(productExtractor);
const result = await generator.forward(llm, { productPage: "..." });

// 完整的 TypeScript 类型推断
console.log(result.product.specs.dimensions.width);
console.log(result.product.reviews[0].comment);

验证与约束

const userRegistration = f()
  .input("userData", f.string())
  .output("user", f.object({
    username: f.string().min(3).max(20),
    email: f.string().email(),
    age: f.number().min(18).max(120),
    password: f.string().min(8).regex("^(?=.*[A-Za-z])(?=.*\\d)", "必须包含字母和数字"),
    bio: f.string().max(500).optional(),
    website: f.string().url().optional(),
  }))
  .build();

可用的约束包括：.min(n)、.max(n)、.email()、.url()、.date()、.datetime()、.regex(pattern, description) 和 .optional()。

验证会在输入和输出阶段同时进行，并在验证失败时自动重试并修正。

带工具的代理（ReAct 模式）

const assistant = ax(
  "question:string -> answer:string",
  {
    functions: [
      { name: "getCurrentWeather", func: weatherAPI },
      { name: "searchNews", func: newsAPI },
    ],
  },
);

const result = await assistant.forward(llm, {
  question: "What's the weather in Tokyo and any news about it?",
});

AxAgent + RLM 处理长上下文

import { agent, AxJSRuntime } from "@ax-llm/ax";

const analyzer = agent(
  "context:string, query:string -> answer:string, evidence:string[]",
  {
    name: "documentAnalyzer",
    description: "Analyze very long documents with recursive code + sub-queries",
    maxSteps: 20,
    rlm: {
      contextFields: ["context"],
      runtime: new AxJSRuntime(),
      maxSubAgentCalls: 40,
      maxRuntimeChars: 2_000, // 共享的 LLM 查询上下文与解释器输出的最大字符限制，
      maxBatchedLlmQueryConcurrency: 6,
      subModel: "gpt-4o-mini",
    },
  },
);

const result = await analyzer.forward(llm, {
  context: veryLongDocument,
  query: "What are the main arguments and supporting evidence?",
});

RLM 模式将长上下文从根提示中分离出来，在持久化的运行时会话中进行迭代分析，并通过有界的子查询来提取语义信息（通常每次子调用不超过 1 万字符）。

AxJSRuntime

AxJSRuntime 是 RLM 和工具式执行所使用的内置 JavaScript 运行时环境。它可在以下环境中运行：

• Node.js/Bun 样式的后端（worker_threads 运行路径）
• Deno 后端（模块 worker 路径）
• 浏览器环境（Web Worker 路径）

它支持：

• 通过 createSession() 创建持久化会话
• 通过 toFunction() 使用函数工具
• 通过 AxJSRuntimePermission 设置沙箱权限

多模态（图像、音频）

const analyzer = ax(`
  image:image, question:string ->
  description:string,
  mainColors:string[],
  category:class "electronics, clothing, food, other",
  estimatedPrice:string
`);

安装

npm install @ax-llm/ax

其他相关包：

# AWS Bedrock 提供商
npm install @ax-llm/ax-ai-aws-bedrock

# Vercel AI SDK v5 集成
npm install @ax-llm/ax-ai-sdk-provider

# 工具：MCP 标准输入输出传输、JS 运行时
npm install @ax-llm/ax-tools

特性

• 支持 15+ 大模型服务商——OpenAI、Anthropic、Google、Mistral、Ollama 等
• 类型安全——全面支持 TypeScript，提供自动补全功能
• 流式处理——实时响应并伴随验证
• 多模态——图像、音频、文本可混合在同一签名中
• 优化——自动提示优化，支持 MiPRO、ACE、GEPA 等技术
• 可观ability——内置 OpenTelemetry 追踪
• 工作流——可通过 AxFlow 组合复杂流程
• RAG——多跳检索与质量循环
• 代理——工具集成与多代理协作
• AxAgent 中的 RLM——递归运行时循环实现长上下文分析
• 零依赖——轻量级、快速且可靠

文档

入门

• 快速入门指南 – 5分钟内完成设置
• 示例指南 – 详尽的示例
• DSPy 概念 – 理解其方法论
• 签名指南 – 类型安全的签名设计

深入探索

• AI 提供商 – 所有提供商、AWS Bedrock、Vercel AI SDK
• AxFlow 工作流 – 构建复杂的 AI 系统
• 优化（MiPRO、ACE、GEPA） – 让程序更智能
• AxAgent & RLM – 代理、子代理、工具以及用于长上下文的 RLM
• 高级 RAG – 生产级搜索与检索

运行示例

OPENAI_APIKEY=your-key npm run tsx ./src/examples/[example-name].ts

核心示例：extract.ts、react.ts、agent.ts、streaming1.ts、multi-modal.ts

生产模式示例：customer-support.ts、food-search.ts、rlm.ts、ace-train-inference.ts、ax-flow-enhanced-demo.ts

查看全部 70 多个示例

社区

• Twitter – 最新动态
• Discord – 帮助与讨论
• GitHub – 给项目点个赞
• DeepWiki – AI 驱动的文档

生产就绪

• 经过生产环境的严格考验
• 稳定的小版本发布
• 全面的测试覆盖率
• 内置 OpenTelemetry
• TypeScript 优先

贡献者

• 作者：@dosco
• GEPA 和 ACE 优化器：@monotykamary

许可证

Apache 2.0

---

npm install @ax-llm/ax

Ax 快速上手指南

Ax 是一个基于 TypeScript 的 AI 应用开发框架，它将 DSPy 的理念引入 JS/TS 生态。你只需定义输入和输出的数据结构，Ax 会自动处理提示词生成、优化、验证及错误重试，支持所有主流大模型。

环境准备

• 运行时环境：Node.js (v18+)、Bun 或 Deno
• 包管理器：npm、yarn、pnpm 或 bun
• API Key：已准备好任意主流 LLM 的 API Key（如 OpenAI, Anthropic, Google 等）
• 语言支持：项目需使用 TypeScript 以获得完整的类型推断体验

安装步骤

使用 npm 安装核心包：

npm install @ax-llm/ax

如需使用特定提供商或高级功能，可选装以下扩展包：

# AWS Bedrock 支持
npm install @ax-llm/ax-ai-aws-bedrock

# Vercel AI SDK v5 集成
npm install @ax-llm/ax-ai-sdk-provider

# 工具链支持 (MCP, JS 运行时等)
npm install @ax-llm/ax-tools

提示：国内开发者若遇到下载缓慢问题，可配置淘宝镜像源： npm config set registry https://registry.npmmirror.com

基本使用

1. 初始化 LLM 客户端

首先导入库并配置你的大模型提供商。以下以 OpenAI 为例：

import { ai, ax } from "@ax-llm/ax";

const llm = ai({ name: "openai", apiKey: process.env.OPENAI_APIKEY });

2. 定义任务签名 (Signature)

使用自然语言描述输入和输出格式，无需编写具体的 Prompt。Ax 会自动将其转换为最优提示词。

// 定义：输入 review (字符串) -> 输出 sentiment (分类：positive, negative, neutral)
const classifier = ax(
  'review:string -> sentiment:class "positive, negative, neutral"',
);

3. 执行推理

调用 forward 方法传入数据，获取结构化结果。

const result = await classifier.forward(llm, {
  review: "This product is amazing!",
});

console.log(result.sentiment); 
// 输出: "positive"

进阶：复杂对象提取与验证

Ax 支持定义嵌套对象和严格的字段验证规则，自动处理重试逻辑。

import { f, ax } from "@ax-llm/ax";

// 定义复杂的输出结构及验证规则
const userSchema = f()
  .input("userData", f.string())
  .output("user", f.object({
    username: f.string().min(3).max(20),
    email: f.string().email(),
    age: f.number().min(18).max(120),
    password: f.string().min(8).regex("^(?=.*[A-Za-z])(?=.*\\d)", "Must contain letter and digit"),
    bio: f.string().max(500).optional(),
  }))
  .build();

const generator = ax(userSchema);

const result = await generator.forward(llm, {
  userData: "Register user: john_doe, john@example.com, 25, pass123"
});

// 结果具有完整的 TypeScript 类型推断
console.log(result.user.email); 

运行示例

安装完成后，你可以直接运行官方提供的示例代码来测试功能：

OPENAI_APIKEY=your-key npm run tsx ./src/examples/extract.ts

更多示例（包括 Agent、流式输出、多模态等）可在 src/examples/ 目录中找到。