ax-llm/ax · 上手攻略

仓库：ax-llm/ax
链接：https://github.com/ax-llm/ax
分类：AI / LLM Framework / TypeScript
作者：Tom
更新：2026-08-20

这是什么

Ax 是 TypeScript 版的 DSPy——一个为 LLM 构建的编程模型和训练框架，但用 TypeScript 实现，号称"几乎就是 TypeScript 的官方 DSPy"。它同一个语义核心还编译到 Python、Java、C++、Go 和 Rust，让你写一次 LLM 程序，跨多个语言生态运行。

核心特点： - 签名驱动的结构化生成（typed structured generation），无需手写 prompt 工程 - Deployment Profile 抽象，改一行 name 就能切换模型提供商 - 流式优先，在模型 token 到来时就解析字段、早期失败、取消无效请求 - GEPA 优化器，few-shot 自举训练，跟 DSPy 的 BootstrapMNLI 同族

解决什么问题

构建 LLM 应用时，传统做法是： 1. 写一个 prompt 字符串 2. 调用 OpenAI SDK（或 Anthropic SDK） 3. 解析 JSON 返回 4. 如果换模型，prompt 要重新调

Ax 把这个过程倒过来：你先声明输入输出的类型签名（signature），Ax 负责渲染 prompt、调用 provider、解析结果、验证类型。换 provider 只需要改一个 name 参数，同一段代码可以无缝切换到不同的模型和部署平台。

对于需要结构化输出（如分类、实体提取、多字段响应）的场景，Ax 的 DSL 特别优雅。

快速安装

TypeScript / Node.js（主力包）

npm install @ax-llm/ax
# 或
yarn add @ax-llm/ax

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

const llm = ai({
  name: "openai",
  apiKey: process.env.OPENAI_APIKEY!,  // ⚠️ 注意变量名
});

Python

pip install axllm

from axllm import ai, ax

Java（Maven Central）

<dependency>
  <groupId>dev.axllm</groupId>
  <artifactId>ax</artifactId>
  <version>...</version>
</dependency>

Go

go get github.com/ax-llm/ax/packages/go

Rust

cargo add axllm

核心用法

1. 结构化生成（AxGen）

用字符串 DSL 声明输入输出：

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

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

// 声明一个分类器
const classify = ax(
  'review:string -> sentiment:class "positive, negative, neutral"'
);

const { sentiment } = await classify.forward(llm, {
  review: "This product is amazing!",
});
// sentiment: "positive" — 类型是 "positive" | "negative" | "neutral" 联合类型

2. 多字段提取

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

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

3. 切换 Provider（只改 name）

// 换到 Anthropic，同一段 classify 代码完全不变
const llm2 = ai({ name: "anthropic", apiKey: process.env.ANTHROPIC_APIKEY! });
const { sentiment } = await classify.forward(llm2, { review: "Worst ever." });

// 换到本地兼容端点
const local = ai({
  name: "openai-compatible",
  apiURL: "https://gateway.example/v1",
  apiKey: process.env.GATEWAY_APIKEY,
  config: { model: "organization/model-id" },
});

支持的 profile name 包括（部分）：openai、anthropic、google-gemini、together、fireworks、deepseek、grok、openai-compatible 等，详见 docs/AI_PROFILES.md。

4. 流式处理

// streamingForward() 返回流，可逐 token 处理
for await (const chunk of classify.streamingForward(llm, { review: "..." })) {
  console.log(chunk);
}

5. GEPA 优化器（few-shot bootstrapping）

⚠️ 优化器具体 API 请参考官方文档，以下为概念说明

Ax 的 GEPA 优化器通过 few-shot 自举生成训练样本，然后用这些样本微调 prompt/chain-of-thought，类似于 DSPy 的 BootstrapMNLI 思路。优化器产出可移植的 artifacts（.json 或类似），之后可以在不同 runtime 应用。

6. 运行多语言示例

Ax 仓库自带全套示例，通过统一 runner 执行，无需记住各语言编译命令：

# 列出所有示例
npm run example -- list

# 运行 Python 示例
npm run example -- python src/examples/python/generation/axgen-openai.py

# 运行 Java 示例
npm run example -- java src/examples/java/generation/BasicGenerationExample.java

# 运行 C++ 示例
npm run example -- cpp src/examples/cpp/generation/basic_generation.cpp

典型适用场景

场景	为什么用 Ax
TypeScript 前端/全栈项目接入 LLM	天生 TS-first，类型安全
多模型切换（OpenAI ↔ Anthropic ↔ Gemini）	同代码，换 name 即可
需要强类型结构化输出的场景	分类、实体提取、表单填充
跨语言团队（Python + TS + Go）	同一语义核心，编译到多语言
需要流式解析 + 早期失败	Ax 在 token 到达时即解析字段

坑与注意

API Key 环境变量名：示例中用 OPENAI_APIKEY（带 KEY 后缀），但 OpenAI 官方 SDK 用 OPENAI_API_KEY（无 KEY 后缀），注意区分——变量名写错不会报错，只会是 undefined。
Profile name 写错会报错：如果你传一个不存在的 profile name（如拼错了 "anthropic"），Ax 会明确告诉你已知 profile ID 列表，而不是静默 fallback 到兼容模式。
结构化输出 mode 依赖 provider 能力：native / function / json_object 三种 mode 各 provider 支持情况不同，Ax 会在请求前检查，不支持就 fail-fast，不会等到解析阶段才发现不支持。
TypeScript 包是源实现：Python/Java/C++/Go/Rust 包都是从 TypeScript 编译生成的，checked-in 在 packages/ 目录，API 稳定性依赖生成流程。
Streaming 延迟基准：官方跑了 Claude Haiku/Sonnet 和 Gemini Flash/Flash Lite 的 benchmark，结果显示 Ax 开销接近裸 SDK 调用，但不同 provider、不同时期结果会有差异，自己跑 streaming-latency.ts 验一下更稳妥。
GEPA 优化器文档：README 对 GEPA 描述较少，详细用法需要看 docs/ 目录下的专项文档或源码 examples。

与同类对比

特性	Ax	DSPy（Python）	LangChain
语言	TypeScript（主）+ 多语言	Python	Python 为主
结构化输出	签名 DSL（强类型）	签名（Python typing）	Prompt 模板
多语言同语义	✅ 原生支持	❌	❌
优化器	GEPA	BootstrapMNLI 等	无
Provider 抽象	Deployment Profile	OpenAI/Anthropic 绑定	LangChain Chains
流式	默认流式，Early parse	有限	支持

Ax 是目前唯一将 DSPy 风格编程模型带到 TypeScript 生态的框架，且真正实现了多语言对齐。如果你用 TypeScript 且需要结构化 LLM 输出，Ax 是最顺滑的选择。

一句话推荐结论

Ax 用签名 DSL 把 LLM 调用变成了类型安全的函数调用，换 provider 如换参数，是 TypeScript 生态里目前最接近"DSPy for TS"的方案——尤其适合需要结构化输出和多模型切换的生产项目。