AI SDK 与 Valibot 集成指南valibotSchema 原理、结构化输出与版本演进全解析【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读ai-sdk/valibot是 AI SDKThe AI Toolkit for TypeScript官方提供的 Valibot 模式支持包它让开发者可以把 Valibot、源码实现 与官方参考文档讲清valibotSchema的用法、底层实现原理、典型实战场景以及从 v0.0.1 到 v3.0.39 的关键演进脉络读完后你将能在 AI SDK 应用中熟练使用 Valibot 完成声明模式—生成数据—校验输出的完整闭环。一、为什么 AI SDK 需要 Valibot 模式支持大型语言模型虽然能生成 JSON 形态的数据但输出往往是不可靠的字符串需要开发者手动提供模式schema并对生成结果做校验。AI SDK 通过在generateText与streamText上提供output属性把结构化对象生成这件事标准化到所有模型提供商之上参见 生成结构化数据指南。在这一体系中开发者可以用 Zod 模式、Valibot 模式或 JSON Schema 三种方式描述期望的数据结构。ai-sdk/valibot正是负责把 Valibot 模式翻译成 AI SDK 可识别的 Schema 对象的桥梁包其核心入口是valibotSchema()函数。二、安装与快速上手包已发布在 npm 上直接安装即可包配置见 package.jsonnpm install ai-sdk/valibot同时它要求 Valibot 及其 JSON Schema 转换工具作为 peer dependency 存在npm install valibot valibot/to-json-schema官方 README 给出的最小可用示例是让模型生成一份千层面食谱模式由 Valibot 定义、通过valibotSchema接入Output.objectimport { anthropic } from ai-sdk/anthropic; import { valibotSchema } from ai-sdk/valibot; import { generateText, Output } from ai; import * as v from valibot; const result await generateText({ model: anthropic(claude-sonnet-4-5-20250929), output: Output.object({ schema: valibotSchema( v.object({ recipe: v.object({ name: v.string(), ingredients: v.array( v.object({ name: v.string(), amount: v.string(), }), ), steps: v.array(v.string()), }), }), ), }), prompt: Generate a lasagna recipe., });执行后result.output会是一个已通过 Valibot 校验、类型安全的强类型对象。注意结构化输出生成在 AI SDK 的多步执行模型中计为一个 step若与工具调用组合使用需要在stopWhen配置中预留足够的步数。三、源码级原理valibotSchema 到底做了什么整个包只有两个源文件核心逻辑全部集中在 valibot-schema.ts全文不过十余行import { toJsonSchema as valibotToJsonSchema } from valibot/to-json-schema; import { jsonSchema, type Schema } from ai-sdk/provider-utils; import * as v from valibot; export function valibotSchema SCHEMA extends v.GenericSchemaunknown, unknown, v.BaseIssueunknown, (valibotSchema: SCHEMA): Schemav.InferOutputSCHEMA { return jsonSchema(valibotToJsonSchema(valibotSchema), { validate: value { const result v.safeParse(valibotSchema, value); return result.success ? { success: true, value: result.output } : { success: false, error: new v.ValiError(result.issues) }; }, }); }从源码可以看出valibotSchema的返回值是一个双面Schema 对象通过jsonSchema()工厂定义于 packages/provider-utils/src/schema.ts创建具备两个关键能力JSON Schema 表示利用valibot/to-json-schema把 Valibot 模式实时转换为标准 JSON Schema。模型提供商拿到这份 JSON Schema 后会以此约束生成内容的形态例如使用 tool / JSON mode。运行时校验通过v.safeParse(valibotSchema, value)对模型返回的原始值做完整校验成功后返回转换后的输出值失败则抛出ValiError携带issues明细。这保证了模式既用于引导生成又用于兜底校验。从类型层面看valibotSchemaSCHEMA的返回类型为Schemav.InferOutputSCHEMA即输出类型完全由 Valibot 模式推断而来v.InferOutput负责完成这一步使整个链路类型安全。API 签名与参数说明可参见官方参考文档 valibotSchema 参考。四、实战场景一结构化数据生成与流式输出valibotSchema最常见的用途就是结构化数据生成。除了generateText它同样可用于streamText实现流式结构化输出——通过partialOutputStream以异步迭代器方式消费逐步生成的局部对象import { streamText, Output } from ai; import { valibotSchema } from ai-sdk/valibot; import * as v from valibot; const { partialOutputStream } streamText({ model, output: Output.object({ schema: valibotSchema( v.object({ name: v.string(), age: v.number(), labels: v.array(v.string()), }), ), }), prompt: Generate information for a test user., }); for await (const partialObject of partialOutputStream) { console.log(partialObject); }几点实战要点依据 生成结构化数据指南Output.object之外的选择AI SDK 的Output还提供Output.text()、Output.array({ element, minItems, maxItems })、Output.choice({ options })、Output.json()等策略其中Output.array的元素、Output.choice均可搭配模式化校验。流式场景的校验边界streamText产生的 partial 输出因数据不完整无法按完整模式校验而Output.array的elementStream每吐出一个元素就是完整且已校验的。给属性加描述用v.string()等基础模式时可借助 Valibot 的元信息能力为属性补充描述等价于 Zod 的.describe()把期望格式、单位等提示给模型提升生成质量。错误处理模型响应无法解析或未通过模式校验时generateText会以AI_NoObjectGeneratedError拒绝若返回结果没有 output例如最终步以tool-calls结束访问result.output会抛出AI_NoOutputGeneratedError两个错误都保留了text、response、usage、cause等字段便于排查。五、实战场景二在工具tools中使用 Valibot 模式valibotSchema的另一大应用场景是工具定义。工具调用基础指南content/docs/02-foundations/04-tools.mdx明确指出工具输入模式可以用 Valibot 通过valibotSchema()声明与 Zod、JSON Schema 并列。例如import { generateText, tool } from ai; import { valibotSchema } from ai-sdk/valibot; import * as v from valibot; const { output } await generateText({ model, tools: { weather: tool({ description: Get the weather for a location, inputSchema: valibotSchema(v.object({ location: v.string() })), execute: async ({ location }) { // 取天气数据 return { temperature: 72, condition: sunny }; }, }), }, prompt: What should I wear in San Francisco today?, });在工具输入上使用 Valibot 的好处与结构化输出一致模式同时承担向模型描述参数结构与校验模型填充的参数值两个职责且与项目的既有 Valibot 模式体系如表单校验、API 入参校验复用同一套定义避免维护两套模式。六、版本演进史从 0.0.1 到 3.0.39 的关键节点CHANGELOG 完整记录了该包随 AI SDK 各主版本迭代的轨迹。虽然其中绝大多数条目是跟随ai-sdk/provider-utils的依赖升级Patch Changes但几个 Major / Minor 节点承载了实质性的技术决策版本类型关键变更0.0.1首发chore (schema/valibot): release valibot schema包首次发布1.0.0MajorAI SDK 5 发布d5f588fchore (valibot): update to valibot 1.1d7cb6b4chore(provider-utils): move over jsonSchema0ff02bbJSON Schema 相关工具迁入 provider-utils2.0.0MajorAI SDK 6 betadee8b05feat: Standard JSON Schema support763d04a3.0.0Major移除所有包的 CommonJS 导出全部改为 ESM-onlyef992f8使用require()的消费者必须切换到 ESMimport语法最低 Node.js 版本提升到 227fc6bd6支持 22 / 24 / 26随 v7 pre-release 启动8359612另有若干发布流程性变更provenance 设置、canary/beta 触发等理解这几个节点的意义0.x → 1.0.0AI SDK 5包从早期的 schema 试验性发布走向稳定同时把 Valibot 依赖升级到 1.1并把jsonSchema工厂统一收拢到ai-sdk/provider-utils——这也是当前实现中valibotSchema直接复用jsonSchema()的由来。2.0.0AI SDK 6 beta加入 Standard JSON Schema 支持进一步对齐跨模式的 Schema 抽象。3.0.0AI SDK 7 时代对整个 monorepo 的模块格式与运行环境做出硬性调整——ESM-only 与 Node.js ≥ 22。如果你正在从旧版本升级这两点是迁移时最需要关注的破坏性变更同时 3.0.0 系列之前的每个小版本如 3.0.1 ~ 3.0.39几乎都只是跟随ai-sdk/provider-utils5.x 的同步发布无独立功能变化。七、依赖、运行环境与包发布约束从 package.json 可以确认当前版本的工程约束peerDependenciesvalibot^1.1.0与valibot/to-json-schema^1.3.0当前仓库开发环境使用valibot^1.4.0与valibot/to-json-schema^1.7.0安装时需一并满足。运行时依赖仅ai-sdk/provider-utilsworkspace 内部包说明它不直接依赖ai主包Schema 对象通过 provider-utils 的类型系统与主包对接。模块格式type: moduleexports只暴露 ESM 入口dist/index.js与 3.0.0 的 ESM-only 决策一致sideEffects: false可安全参与 tree-shaking。运行环境engines.node 22。发布配置access: public且启用provenance对应 CHANGELOG 中9f0e36c: trigger release for all packages after provenance setup一条。从源码打包层面看files字段同时包含dist与src目录便于开发者阅读与调试对应 2.0.x 时代8dc54db: chore: add src folders to package bundle与4de5a1d: chore: excluded tests from src folder两条演进。八、更多资源若想继续深入仓库内可直接查阅以下内容包源码src/valibot-schema.ts、src/index.ts包文档README.md、CHANGELOG.md官方参考valibotSchema API 参考使用指南生成结构化数据、工具与工具调用底层 Schema 抽象provider-utils 的 schema.ts结合官方示例仓库如examples/next与examples/node目录下的结构化生成示例可以快速跑通端到端流程。整体来看ai-sdk/valibot是小而精的集成层把 Valibot 的运行时校验能力与 AI SDK 的标准化 Schema 抽象无缝对接让 Valibot 用户在不引入第二套模式体系的前提下获得类型安全的结构化输出与工具参数校验体验。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AI SDK 与 Valibot 集成指南：valibotSchema 原理、结构化输出与版本演进全解析
AI SDK 与 Valibot 集成指南valibotSchema 原理、结构化输出与版本演进全解析【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读ai-sdk/valibot是 AI SDKThe AI Toolkit for TypeScript官方提供的 Valibot 模式支持包它让开发者可以把 Valibot、源码实现 与官方参考文档讲清valibotSchema的用法、底层实现原理、典型实战场景以及从 v0.0.1 到 v3.0.39 的关键演进脉络读完后你将能在 AI SDK 应用中熟练使用 Valibot 完成声明模式—生成数据—校验输出的完整闭环。一、为什么 AI SDK 需要 Valibot 模式支持大型语言模型虽然能生成 JSON 形态的数据但输出往往是不可靠的字符串需要开发者手动提供模式schema并对生成结果做校验。AI SDK 通过在generateText与streamText上提供output属性把结构化对象生成这件事标准化到所有模型提供商之上参见 生成结构化数据指南。在这一体系中开发者可以用 Zod 模式、Valibot 模式或 JSON Schema 三种方式描述期望的数据结构。ai-sdk/valibot正是负责把 Valibot 模式翻译成 AI SDK 可识别的 Schema 对象的桥梁包其核心入口是valibotSchema()函数。二、安装与快速上手包已发布在 npm 上直接安装即可包配置见 package.jsonnpm install ai-sdk/valibot同时它要求 Valibot 及其 JSON Schema 转换工具作为 peer dependency 存在npm install valibot valibot/to-json-schema官方 README 给出的最小可用示例是让模型生成一份千层面食谱模式由 Valibot 定义、通过valibotSchema接入Output.objectimport { anthropic } from ai-sdk/anthropic; import { valibotSchema } from ai-sdk/valibot; import { generateText, Output } from ai; import * as v from valibot; const result await generateText({ model: anthropic(claude-sonnet-4-5-20250929), output: Output.object({ schema: valibotSchema( v.object({ recipe: v.object({ name: v.string(), ingredients: v.array( v.object({ name: v.string(), amount: v.string(), }), ), steps: v.array(v.string()), }), }), ), }), prompt: Generate a lasagna recipe., });执行后result.output会是一个已通过 Valibot 校验、类型安全的强类型对象。注意结构化输出生成在 AI SDK 的多步执行模型中计为一个 step若与工具调用组合使用需要在stopWhen配置中预留足够的步数。三、源码级原理valibotSchema 到底做了什么整个包只有两个源文件核心逻辑全部集中在 valibot-schema.ts全文不过十余行import { toJsonSchema as valibotToJsonSchema } from valibot/to-json-schema; import { jsonSchema, type Schema } from ai-sdk/provider-utils; import * as v from valibot; export function valibotSchema SCHEMA extends v.GenericSchemaunknown, unknown, v.BaseIssueunknown, (valibotSchema: SCHEMA): Schemav.InferOutputSCHEMA { return jsonSchema(valibotToJsonSchema(valibotSchema), { validate: value { const result v.safeParse(valibotSchema, value); return result.success ? { success: true, value: result.output } : { success: false, error: new v.ValiError(result.issues) }; }, }); }从源码可以看出valibotSchema的返回值是一个双面Schema 对象通过jsonSchema()工厂定义于 packages/provider-utils/src/schema.ts创建具备两个关键能力JSON Schema 表示利用valibot/to-json-schema把 Valibot 模式实时转换为标准 JSON Schema。模型提供商拿到这份 JSON Schema 后会以此约束生成内容的形态例如使用 tool / JSON mode。运行时校验通过v.safeParse(valibotSchema, value)对模型返回的原始值做完整校验成功后返回转换后的输出值失败则抛出ValiError携带issues明细。这保证了模式既用于引导生成又用于兜底校验。从类型层面看valibotSchemaSCHEMA的返回类型为Schemav.InferOutputSCHEMA即输出类型完全由 Valibot 模式推断而来v.InferOutput负责完成这一步使整个链路类型安全。API 签名与参数说明可参见官方参考文档 valibotSchema 参考。四、实战场景一结构化数据生成与流式输出valibotSchema最常见的用途就是结构化数据生成。除了generateText它同样可用于streamText实现流式结构化输出——通过partialOutputStream以异步迭代器方式消费逐步生成的局部对象import { streamText, Output } from ai; import { valibotSchema } from ai-sdk/valibot; import * as v from valibot; const { partialOutputStream } streamText({ model, output: Output.object({ schema: valibotSchema( v.object({ name: v.string(), age: v.number(), labels: v.array(v.string()), }), ), }), prompt: Generate information for a test user., }); for await (const partialObject of partialOutputStream) { console.log(partialObject); }几点实战要点依据 生成结构化数据指南Output.object之外的选择AI SDK 的Output还提供Output.text()、Output.array({ element, minItems, maxItems })、Output.choice({ options })、Output.json()等策略其中Output.array的元素、Output.choice均可搭配模式化校验。流式场景的校验边界streamText产生的 partial 输出因数据不完整无法按完整模式校验而Output.array的elementStream每吐出一个元素就是完整且已校验的。给属性加描述用v.string()等基础模式时可借助 Valibot 的元信息能力为属性补充描述等价于 Zod 的.describe()把期望格式、单位等提示给模型提升生成质量。错误处理模型响应无法解析或未通过模式校验时generateText会以AI_NoObjectGeneratedError拒绝若返回结果没有 output例如最终步以tool-calls结束访问result.output会抛出AI_NoOutputGeneratedError两个错误都保留了text、response、usage、cause等字段便于排查。五、实战场景二在工具tools中使用 Valibot 模式valibotSchema的另一大应用场景是工具定义。工具调用基础指南content/docs/02-foundations/04-tools.mdx明确指出工具输入模式可以用 Valibot 通过valibotSchema()声明与 Zod、JSON Schema 并列。例如import { generateText, tool } from ai; import { valibotSchema } from ai-sdk/valibot; import * as v from valibot; const { output } await generateText({ model, tools: { weather: tool({ description: Get the weather for a location, inputSchema: valibotSchema(v.object({ location: v.string() })), execute: async ({ location }) { // 取天气数据 return { temperature: 72, condition: sunny }; }, }), }, prompt: What should I wear in San Francisco today?, });在工具输入上使用 Valibot 的好处与结构化输出一致模式同时承担向模型描述参数结构与校验模型填充的参数值两个职责且与项目的既有 Valibot 模式体系如表单校验、API 入参校验复用同一套定义避免维护两套模式。六、版本演进史从 0.0.1 到 3.0.39 的关键节点CHANGELOG 完整记录了该包随 AI SDK 各主版本迭代的轨迹。虽然其中绝大多数条目是跟随ai-sdk/provider-utils的依赖升级Patch Changes但几个 Major / Minor 节点承载了实质性的技术决策版本类型关键变更0.0.1首发chore (schema/valibot): release valibot schema包首次发布1.0.0MajorAI SDK 5 发布d5f588fchore (valibot): update to valibot 1.1d7cb6b4chore(provider-utils): move over jsonSchema0ff02bbJSON Schema 相关工具迁入 provider-utils2.0.0MajorAI SDK 6 betadee8b05feat: Standard JSON Schema support763d04a3.0.0Major移除所有包的 CommonJS 导出全部改为 ESM-onlyef992f8使用require()的消费者必须切换到 ESMimport语法最低 Node.js 版本提升到 227fc6bd6支持 22 / 24 / 26随 v7 pre-release 启动8359612另有若干发布流程性变更provenance 设置、canary/beta 触发等理解这几个节点的意义0.x → 1.0.0AI SDK 5包从早期的 schema 试验性发布走向稳定同时把 Valibot 依赖升级到 1.1并把jsonSchema工厂统一收拢到ai-sdk/provider-utils——这也是当前实现中valibotSchema直接复用jsonSchema()的由来。2.0.0AI SDK 6 beta加入 Standard JSON Schema 支持进一步对齐跨模式的 Schema 抽象。3.0.0AI SDK 7 时代对整个 monorepo 的模块格式与运行环境做出硬性调整——ESM-only 与 Node.js ≥ 22。如果你正在从旧版本升级这两点是迁移时最需要关注的破坏性变更同时 3.0.0 系列之前的每个小版本如 3.0.1 ~ 3.0.39几乎都只是跟随ai-sdk/provider-utils5.x 的同步发布无独立功能变化。七、依赖、运行环境与包发布约束从 package.json 可以确认当前版本的工程约束peerDependenciesvalibot^1.1.0与valibot/to-json-schema^1.3.0当前仓库开发环境使用valibot^1.4.0与valibot/to-json-schema^1.7.0安装时需一并满足。运行时依赖仅ai-sdk/provider-utilsworkspace 内部包说明它不直接依赖ai主包Schema 对象通过 provider-utils 的类型系统与主包对接。模块格式type: moduleexports只暴露 ESM 入口dist/index.js与 3.0.0 的 ESM-only 决策一致sideEffects: false可安全参与 tree-shaking。运行环境engines.node 22。发布配置access: public且启用provenance对应 CHANGELOG 中9f0e36c: trigger release for all packages after provenance setup一条。从源码打包层面看files字段同时包含dist与src目录便于开发者阅读与调试对应 2.0.x 时代8dc54db: chore: add src folders to package bundle与4de5a1d: chore: excluded tests from src folder两条演进。八、更多资源若想继续深入仓库内可直接查阅以下内容包源码src/valibot-schema.ts、src/index.ts包文档README.md、CHANGELOG.md官方参考valibotSchema API 参考使用指南生成结构化数据、工具与工具调用底层 Schema 抽象provider-utils 的 schema.ts结合官方示例仓库如examples/next与examples/node目录下的结构化生成示例可以快速跑通端到端流程。整体来看ai-sdk/valibot是小而精的集成层把 Valibot 的运行时校验能力与 AI SDK 的标准化 Schema 抽象无缝对接让 Valibot 用户在不引入第二套模式体系的前提下获得类型安全的结构化输出与工具参数校验体验。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考