@dosco: PEEK 即将登陆 ax-agent https://github.com/ax-llm/ax

PEEK 即将登陆 ax-agent https://t.co/CoU6qMUo5M https://t.co/nWwtLsxUNs — # ax-llm/ax 来源：https://github.com/ax-llm/ax # Ax —— 面向 TypeScript 的 DSPy 自动提示生成、RLM Agent，以及 15+ 提供商的统一 API。经过生产验证。 NPM（https://www.npmjs.com/package/@ax-llm/ax） Discord（https://discord.gg/DSHg3dU7dW） Twitter（https://twitter.com/dosco） ## Ax 是什么 - 一个轻量无依赖的 TypeScript 库，将 DSPy 编程模型引入 JS/TS 运行时。 - 你声明一个签名（字符串 DSL、流式 f() 构建器、或任意 Standard Schema v1 校验器——Zod、Valibot、ArkType）。Ax 在运行时将其编译为提示，调用 AI，解析输出，并返回一个完整类型化的值。 - 相同的签名可直接接入 Agent、工作流、优化器和沙箱 JS 运行时——无需重写提示。 - 支持 NodeJS、Bun、Deno 以及所有浏览器。 mermaid flowchart LR S["Signature (string, f, zod)"] --> P["Prompt"] P --> AI["AI"] AI --> R["Streaming parser"] R --> O["Typed output"] X["GEPA / ACE optimizer"] --> P ## 30 秒上手 typescript 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" — 类型为字面量联合 无需提示工程。将 name: "openai" 改为 "anthropic"、"google-gemini"、"mistral"、"ollama" 等——签名相同，代码相同。 ## 提供商原生速度 Ax 旨在保持与直接提供商调用相同的延迟级别，同时增加类型化输出、校验、重试、工具、追踪和记忆。热路径故意精简：渲染签名、调用提供商、解析结果、返回类型化值。 流式是默认模式，因为 Ax 可以在模型完成前做有用工作：解析到达的字段、运行流式断言、提前失败、取消正在进行的流、并在不消耗 token 于已知无效的输出上时启动修正。当你只想要最终对象时，forward() 仍然返回一个；当你想要实时输出时，streamingForward() 直接暴露流。 仓库包含一个实时基准测试，用于检查你在自己的提供商和模型上的开销： bash AX_STREAM_BENCH_PROVIDER=anthropic AX_STREAM_BENCH_MODEL=claude-sonnet-4-5-20250929 AX_STREAM_BENCH_RUNS=2 AX_STREAM_BENCH_WARMUP_RUNS=0 npm run tsx src/examples/streaming-latency.ts AX_STREAM_BENCH_PROVIDER=google-gemini AX_STREAM_BENCH_MODEL=gemini-2.5-flash AX_STREAM_BENCH_RUNS=2 AX_STREAM_BENCH_WARMUP_RUNS=0 npm run tsx src/examples/streaming-latency.ts 最近在 Claude Haiku/Sonnet 和 Gemini Flash/Flash Lite 上的运行显示，提供商队列和模型生成占主导地位；AxGen 在提供结构化输出控制循环（通常由应用代码处理的）的同时，保持接近原始 ai.chat() 路径的延迟。 ## 示例 ### 结构化提取 typescript 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(), }); ### 使用 f() 嵌套对象 typescript import { ax, f } 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 gen = ax(productExtractor); const { product } = await gen.forward(llm, { productPage: "..." }); // product.specs.dimensions.width 类型从头到尾完整推断 ### Standard Schema v1（Zod / Valibot / ArkType） 任何 Standard Schema v1 校验器都可以在 f.* 被接受的地方使用——字段级别、整个对象级别、或 fn() 工具上。相同的重试管道，相同的类型推断，无需适配器。 typescript import { z } from "zod"; import { ax, f, fn } from "@ax-llm/ax"; // (1) 字段级 zod —— 可与 f.* 字段自由混合 const reviewSentiment = ax( f() .input("productName", z.string().describe("Reviewed product")) .input("reviewText", z.string().min(10)) .output("sentiment", z.enum(["positive", "neutral", "negative"])) .output("score", z.number().min(1).max(10)) .output("keyPoints", z.array(z.string())) .build(), ); // (2) 整个对象 zod —— 一次性声明，分解为有序字段 const productSummary = ax( f() .input(z.object({ productName: z.string(), buyerProfile: z.string() })) .output(z.object({ headline: z.string(), pros: z.array(z.string()), cons: z.array(z.string()), recommendation: z.enum(["buy", "wait", "skip"]), })) .build(), ); // (3) 在 fn() 上使用整个对象 zod —— 类型化工具定义 const lookupProduct = fn("lookupProduct") .description("Look up a product by name") .arg(z.object({ productName: z.string().min(1), includeSpecs: z.boolean().optional() })) .returns(z.object({ price: z.number(), inStock: z.boolean(), rating: z.number().min(1).max(5) })) .handler(async ({ productName }) => ({ price: 79.99, inStock: true, rating: 4.3 })) .build(); .min()、.max()、.email()、.url()、.regex() 会反馈给正常的重试管道；.refine()、.transform() 和 .superRefine() 在解析时对完整字段值执行，同时在流式和非流式模式下都有效。缓存断点和内部推理字段使用配套选项：{ cache: true }、{ internal: true }。多模态输入（image、audio、file）仍然使用 f.*。可运行示例：src/examples/standard-schema.ts。 ### 工具（ReAct） typescript const assistant = ax("question:string -> answer:string", { functions: [ { name: "getCurrentWeather", func: weatherAPI }, { name: "searchNews", func: newsAPI }, ], }); const { answer } = await assistant.forward(llm, { question: "What's the weather in Tokyo and any news about it?", }); ### 多模态 typescript const analyze = ax(` image:image, question:string -> description:string, mainColors:string[], category:class "electronics, clothing, food, other", estimatedPrice:string `); ### 对话式音频 对有限制的 .chat() 回合的音频输入/输出直接在 AI 服务上支持。生成的音频位于 result.audio 中，不在 DSPy 签名输出字段中。OpenAI 同时支持基于请求的音频聊天（gpt-audio、gpt-audio-mini）和实时语音/转录模型（gpt-realtime-2、gpt-realtime-whisper）。Gemini 原生音频在相同的 .chat() 形状下使用 Live API。 typescript import WebSocket from "ws"; import { ai, axAIOpenAIRealtimeDefaultConfig, axAIOpenAIRealtimeTranscriptionDefaultConfig, } from "@ax-llm/ax"; const voice = ai({ name: "openai", apiKey: process.env.OPENAI_APIKEY!, config: axAIOpenAIRealtimeDefaultConfig(), // gpt-realtime-2 }); const stream = await voice.chat( { chatPrompt: [{ role: "user", content: "Say hello out loud." }] }, { stream: true, webSocket: WebSocket }, ); for await (const chunk of stream) { const audio = chunk.results[0]?.audio; if (audio?.isDelta) { // base64 pcm16 音频字节 process.stdout.write("."); } } const transcriber = ai({ name: "openai", apiKey: process.env.OPENAI_APIKEY!, config: axAIOpenAIRealtimeTranscriptionDefaultConfig(), // gpt-realtime-whisper }); 可运行示例：src/examples/audio-chat.ts。 ## AxAgent AxAgent 是一个三阶段管道，将签名转换为一个长期运行、使用工具的 Actor。每次 forward() 调用都会运行蒸馏器 → 执行器 → 响应器。 mermaid flowchart LR IN["inputs"] --> D["Distiller"] D --> E["Executor (RLM loop)"] E --> RT["AxJSRuntime sandbox"] E --> FN["functions / child agents"] E --> M["recall - memories"] E --> SK["consult - skills"] E --> RES["Responder"] RES --> OUT["typed output"] typescript import { agent, AxJSRuntime } from "@ax-llm/ax"; const analyzer = agent( "context:string, query:string -> answer:string, evidence:string[]", { agentIdentity: { name: "documentAnalyzer", description: "Analyze long documents with iterative code + sub-queries", }, contextFields: ["context"], runtime: new AxJSRuntime(), maxTurns: 20, maxRuntimeChars: 2_000, contextPolicy: { preset: "checkpointed", budget: "balanced" }, executorOptions: { model: "gpt-4o-mini" }, }, ); const result = await analyzer.forward(llm, { context: veryLongDocument, query: "What are the main arguments and supporting evidence?", }); 递归运行时（RLM） 将长上下文保留在根提示之外：执行器在一个持久的沙箱会话中运行 JS，使用 llmQuery(...) 子调用缩小上下文，并使用检查点重放，使得较早的回合折叠为摘要而不是无限增长提示。可运行示例：src/examples/rlm-agent-controlled.ts、src/examples/rlm-discovery.ts。 ### 记忆、技能、沙箱运行时 这是 agent(...) 上的三个正交选项。根据任务需求选择加入。 记忆 —— 向量 / BM25 / KV 查找，Actor 通过 await recall([...]) 控制。结果会进入 inputs.memories 供下一回合使用。生命周期为一次 .forward()；持久化到外部以跨调用携带。 typescript const myAgent = agent("task:string -> plan:string", { onMemoriesSearch: async (searches, alreadyLoaded) => { const skip = new Set(alreadyLoaded.map((m) => m.id)); return (await myVectorDB.searchBatch(searches, { topK: 3 })) .filter((m) => !skip.has(m.id)); }, onUsedMemories: (results) => console.log("[memories]", results.map((r) => r.id)), }); 技能 —— 指南 / 操作手册，Actor 通过 await consult([...]) 按需拉入。加载的技能会在执行器系统提示中展示在“已加载技能”下，并跨 .forward() 调用持久化。 typescript const myAgent = agent("task:string -> plan:string", { onSkillsSearch: async (searches) => mySkillStore.searchBatch(searches, { topK: 2 }), // 或者静态预加载——不需要 consult()： skills: [{ name: "release-checklist", content: "1. Bump version\n2. ..." }], }); 沙箱 JS 运行时 —— AxJSRuntime 是默认的；它默认是加固的，并且在 Node、Bun（smol: true 工作线程）、Deno 和浏览器之间可移植。功能通过权限选择加入。 typescript import { AxJSRuntime, AxJSRuntimePermission } from "@ax-llm/ax"; const runtime = new AxJSRuntime({ permissions: [AxJSRuntimePermission.NETWORK], // 仅授予 fetch }); 默认：import() 被阻止，内部变量冻结，ShadowRealm 锁定，工作线程 IPC 锁定，并且在 Node 20+ 上，OS 权限模型会自动作为第二道防线。仅在任务需要时添加 FILESYSTEM、STORAGE、CHILD_PROCESS 等。可运行示例：src/examples/rlm-memories-and-skills.ts。 ## AxFlow + 优化 AxFlow 是一个类型化、可链式调用的工作流运行器——定义节点，通过 execute 连接状态，用 map 最终化。随着节点添加，状态类型会演化，因此最终的映射器是完全类型检查的。 typescript import { AxAI, AxAIOpenAIModel, AxGEPA, flow } from "@ax-llm/ax"; const emailFlow = flow<{ emailText: string }>() .description("Email Priority", "Classify priority and write a one-line rationale.") .n("classifier", 'emailText:string -> priority:class "high, normal, low"') .n("rationale", "emailText:string, priority:string -> rationale:string") .e("classifier", (s) => ({ emailText: s.emailText })) .e("rationale", (s) => ({ emailText: s.emailText, priority: s.classifierResult.priority })) .m((s) => ({ priority: s.classifierResult.priority, rationale: s.rationaleResult.rationale, })); 使用 GEPA（多目标 Pareto 优化器）调优整个工作流。定义一个返回一个或多个命名分数的度量；GEPA 探索提示空间并返回一个 Pareto 前沿。 typescript const student = new AxAI({ name: "openai", apiKey: process.env.OPENAI_APIKEY!, config: { model: AxAIOpenAIModel.GPT4OMini } }); const teacher = new AxAI({ name: "openai", apiKey: process.env.OPENAI_APIKEY!, config: { model: AxAIOpenAIModel.GPT4O } }); const optimizer = new AxGEPA({ studentAI: student, teacherAI: teacher, numTrials: 16, minibatch: true, minibatchSize: 6, seed: 42, }); const result = await optimizer.compile( emailFlow, trainSet, async ({ prediction, example }) => ({ accuracy: prediction.priority === example.priority ? 1 : 0, brevity: (prediction.rationale?.length ?? 0) <= 60 ? 1 : 0.4, }), { auto: "medium", validationExamples: valSet, maxMetricCalls: 240 }, ); // result.paretoFront, result.hypervolume, result.paretoFrontSize ACE（自动课程提取）以相同方式工作，通过 new AxACE({...}).compile(...) —— 基于剧本的迭代优化。参见 src/examples/ace-train-inference.ts 和 src/examples/gepa-flow.ts。 ## 能力 | 能力 | 入口点 | 说明 | |—|—|—| | 字符串签名 DSL | ax、s | 'review:string -> sentiment:class "..."' | | 流式签名构建器 | f | 类型化嵌套、约束、校验错误时重试 | | Standard Schema v1 | f、fn | Zod、Valibot、ArkType——字段级或整个对象级 | | 工具/函数调用 | fn、functions: 选项 | 类型化参数、类型化返回值、异步处理程序 | | 流式 + 校验 | .streamingForward() | 在字段边界处解析 | | 多模态 | f.image、f.audio、.chat({ audio }) | OpenAI、Gemini、Anthropic | | 对话式音频 | .chat() + result.audio | OpenAI gpt-audio*、gpt-realtime-2、gpt-realtime-whisper；Gemini Live 原生音频 | | 工作流 | flow、AxFlow | 类型化 DAG，并行，分支，子上下文 | | 优化 | AxGEPA、AxACE、AxBootstrapFewShot | Pareto 前沿，剧本课程，少样本 | | Agent 循环 | agent、AxAgent | 蒸馏器 → 执行器 → 响应器 | | 记忆 | onMemoriesSearch、recall(...) | 向量/BM25 支持的上下文加载器 | | 技能 | onSkillsSearch、consult(...) | 按需的提示部分加载器 | | 沙箱 JS | AxJSRuntime、AxJSRuntimePermission | Node、Bun、Deno、浏览器 | | 递归运行时 (RLM) | agent({ runtime, contextFields }) | 长上下文 REPL，带检查点重放 | | 提供商 | ai({ name: ... }) | OpenAI、Anthropic、Gemini、Mistral、Cohere、Groq、Together、Ollama、OpenRouter、Bedrock（独立包）、Reka、DeepSeek、Grok、HuggingFace、WebLLM | | 可观测性 | OpenTelemetry、executorTurnCallback、onFunctionCall | 每回合遥测，工具调用追踪 | | RAG | AxDBManager、AxDefaultResultReranker | 多跳检索，带质量循环 | | MCP | AxMCPClient、AxMCPHTTPSSETransport、AxMCPStreambleHTTPTransport | 将任意 MCP 服务器用作工具源 | ## 安装 bash npm install @ax-llm/ax 可选包： bash npm install @ax-llm/ax-ai-aws-bedrock # AWS Bedrock 提供商 npm install @ax-llm/ax-ai-sdk-provider # Vercel AI SDK v5 集成 npm install @ax-llm/ax-tools # MCP stdio 传输，JS 运行时扩展 ## 文档 入门 - 快速入门（https://github.com/ax-llm/ax/blob/main/src/ax/README.md） - 示例（https://github.com/ax-llm/ax/blob/main/src/docs/src/content/docs/examples.md） - DSPy 概念（https://github.com/ax-llm/ax/blob/main/src/docs/src/content/docs/dspy.md） - 签名（https://github.com/ax-llm/ax/blob/main/src/ax/skills/ax-signature.md） 深入 - AI 提供商（https://github.com/ax-llm/ax/blob/main/src/ax/skills/ax-ai.md） - 音频 I/O（https://github.com/ax-llm/ax/blob/main/src/ax/skills/ax-audio.md） - AxFlow 工作流（https://github.com/ax-llm/ax/blob/main/src/ax/skills/ax-flow.md） - 优化（GEPA, ACE）（https://githu