Sanity Auto-Tag 函数实战基于 AI 的博客文章自动打标签全流程指南【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity本文以 Sanity 仓库中的 auto-tag 函数示例 为核心完整讲解如何借助 Sanity Functions 与 Agent Actions在博客文章发布时自动生成 3 个相关标签并复用既有标签维持词表一致。读完本文你将掌握从 schema 字段定义、蓝图Blueprint配置、本地测试到生产部署的完整链路并能基于源码自由定制标签数量、目标字段与触发过滤条件。背景与解决的问题在传统编辑流程中内容创作者需要手动为每篇博客文章打标签。这种做法不仅耗时每篇约 2-3 分钟还容易导致整个内容库中标签命名不一致——有人写javascript有人写JavaScript还有人写js最终削弱了内容的可发现性与组织质量。auto-tag 这个 Sanity Function 的目标就是解决这个问题自动触发文章创建或内容字段更新时自动执行无需人工介入AI 分析基于文章content字段的正文内容利用 Sanity 的 AI 能力生成语义相关的标签词表一致性生成标签前会查询其他已发布文章使用过的标签优先复用已有标签避免词表无限膨胀自动回写将生成的标签直接写回文档的tags数组字段发布即可用。从源码看这个示例的核心实现在 examples/functions/auto-tag/index.ts依赖sanity/client与sanity/functions两个包见 package.json。前置要求在开始之前请确认满足以下条件一个启用了 Functions 能力的 Sanity 项目schema 中包含post文档类型且具备content字段Portable Text 富文本类型用于内容分析tags数组字段用于存储生成的标签可访问 Sanity 的 AI 能力Agent Actions 功能本地开发环境使用Node.js v22.x与生产运行时保持一致Sanity CLI 版本v3.92.0 或以上部署时需要。该函数与 Sanity 官方 clean 系列模板兼容。官方推荐先在本地安装任意 clean 模板后在模板项目中试用本函数。为 schema 添加 tags 字段如果使用nextjs-clean模板需要先在studio/src/schemaTypes/documents/post.ts中给fields数组添加如下字段defineField({ name: tags, title: Tags, type: array, of: [{ type: string }], description: Tags will be automatically generated when you publish a post, }),然后在/studio目录下部署更新后的 schema# /studio npx sanity schema deploy函数实现原理先看核心实现 examples/functions/auto-tag/index.ts 的完整逻辑import {createClient} from sanity/client import {documentEventHandler} from sanity/functions export const handler documentEventHandler(async ({context, event}) { const client createClient({ ...context.clientOptions, apiVersion: vX, useCdn: false, }) const {data} event const {local} context // local is true when running locally try { const result await client.agent.action.generate({ noWrite: local ? true : false, // if local is true, we dont want to write to the document, just return the result for logging instructionParams: { content: { type: field, path: content, }, tagsUsedInOtherPosts: { type: groq, query: array::unique(*[_type post _id ! $id defined(tags)].tags[]), params: { id: data._id, }, }, }, instruction: Based on the $content, create 3 relevant tags. Attempt to use $tagsUsedInOtherPosts first if they fit the context. Tags should be simple lowercase words strings and no brackets., target: { path: tags, }, documentId: data._id, schemaId: _.schemas.default, forcePublishedWrite: true, }) console.log( local ? Generated tags (LOCAL TEST MODE - Content Lake not updated): : Generated tags:, result.tags, ) } catch (error) { console.error(Error occurred during tag generation:, error) } })关键参数逐项解读context.clientOptions由 Sanity Functions 运行时注入的客户端配置这里基于它创建了一个apiVersion: vX、useCdn: false的客户端。useCdn: false很关键——AI 回写与读取都要求实时数据不能走 CDN 缓存。noWrite本地测试时置为trueAI 只返回生成结果、不写入 Content Lake生产环境置为false才会真正落盘。源码注释明确写了这一点。instructionParams.contenttype: field表示从文档的content字段直接取正文内容作为$content变量注入指令。instructionParams.tagsUsedInOtherPoststype: groq表示通过一段 GROQ 查询动态取数。这条查询array::unique(*[_type post _id ! $id defined(tags)].tags[])的含义是收集所有_type post、ID 不等于当前文档、且已定义tags的文档的全部标签再经array::unique去重——这正是复用既有标签、维持词表一致的实现来源。当前文档 ID 通过params.id传入避免把自己的标签也算进去。instructionAI 指令模板告诉模型基于$content创建 3 个相关标签如果$tagsUsedInOtherPosts中的标签符合语境则优先使用标签应为简单的小写单词字符串不要带括号。target.pathAI 生成结果的回写路径这里是tags字段。documentId目标文档 ID来自事件的data._id。schemaId: _.schemas.default目标 schema 标识。forcePublishedWrite: true强制写入已发布版本确保标签立即可见。函数将生成结果打印到日志本地模式会明确提示 Content Lake 未更新出错时捕获并打印错误不会导致事件链路崩溃。蓝图配置与部署步骤重要提示以下命令需要在项目根目录执行不要进入studio/目录。1. 初始化示例如果你还没有初始化 blueprints先执行npx sanity blueprints init期间会提示选择你的组织organization和 Sanity studio。然后添加 auto-tag 示例npx sanity blueprints add function --example auto-tag2. 将函数加入蓝图配置在项目根目录的sanity.blueprint.ts中注册该文档函数// sanity.blueprint.ts import {defineBlueprint, defineDocumentFunction} from sanity/blueprints export default defineBlueprint({ resources: [ defineDocumentFunction({ name: auto-tag, src: ./functions/auto-tag, memory: 2, timeout: 30, event: { on: [create, update], filter: _type post (delta::changedAny(content) || (delta::operation() create defined(content))), projection: {_id}, }, }), ], })各配置项的含义name函数名称本地测试与部署时以此引用src函数源码目录相对于项目根目录memory分配给函数的内存GB示例为 2timeout函数超时时间秒示例为 30event.on触发事件类型create/update表示文档创建与更新时触发event.filter触发过滤条件仅当_type post且满足content字段发生变更或文档刚创建且content已定义时才执行避免无关更新白白消耗 AI 调用event.projection注入事件负载的字段投影这里只取{_id}即可满足实现所需。这一配置在示例的 package.json 中也有对应声明blueprintResourceItem字段且 examples/sanity.blueprint.ts 会遍历functions/目录自动发现并注册所有函数示例可作为理解配置格式的参考。3. 安装依赖在项目根目录执行npm install函数运行所需的依赖为sanity/client^8.6.1与sanity/functions^1.7.2版本以 package.json 为准。4. 确保 schema 已部署进入 studio 目录执行# In the studio/ folder npx sanity schema deploy本地测试函数生产部署前务必先在本地验证函数行为。简单测试命令使用数据集中的真实文档 ID 测试npx sanity functions test auto-tag --document-id insert-document-id --dataset production --with-user-token将insert-document-id替换为数据集中的实际文档 IDproduction替换为你的数据集名称。交互式开发模式启动开发服务器进行交互式测试npx sanity functions dev测试建议使用真实文档 ID文档函数要求 ID 在数据集中真实存在本地使用 Node.js v22.x与生产运行时保持一致覆盖边界场景测试无内容、或已带标签的文章查看 CLI 日志函数日志会输出在 CLI 中用于排查问题先关掉 AI 写入可在函数中临时设置noWrite: true先验证分析流程准备测试内容如果没有未打标签的文章先创建一些测试文档。生产部署本地测试通过后即可部署。注意部署前请确认你的账户拥有该项目的 Deploy Studio 权限。部署前置条件Sanity CLI v3.92.0 或以上项目的 Deploy Studio 权限Node.js v22.x匹配生产运行时。部署步骤核对蓝图配置确认sanity.blueprint.ts已正确配置 auto-tag 函数见上文配置代码。部署蓝图在项目根目录执行npx sanity blueprints deploy该命令会依次完成打包你的函数代码上传到 Sanity 的基础设施配置文章发布相关的事件触发器让 auto-tag 函数在生产环境生效。验证部署结果部署完成后可通过以下方式确认在 Sanity Manage 控制台的 API Functions 下查看函数状态发布一篇没有标签的新文章确认标签被自动生成在 CLI 中监控函数日志。部署最佳实践先充分本地测试任何改动都应先在本地验证再部署监控 AI 用量Agent Actions 有使用额度与成本可到 Manage 控制台的 Settings 查看详情避免递归触发过滤条件中通过!defined(tags)之类的判断防止函数给文档写完标签后再次触发自身使用精确的过滤条件当前 filter 只针对没有标签的 post避免不必要的执行开销。常见故障排查错误Deploy Studio permission required原因当前账户没有该项目的部署权限解决请项目管理员为你授予 Deploy Studio 权限。部署后函数没有生成标签原因文章可能已有标签或 schema 字段配置不正确解决改用没有既有标签的文章测试并确认tags字段已存在于 schema 中。运行流程全景当编辑发布一篇未打标签的新博客文章时整个流程如下触发文档 create/update 事件命中过滤条件content字段变更分析函数读取文章的content字段交给 AI 分析取词通过 GROQ 查询收集其他已发布文章的既有标签用于词表对齐生成AI 生成 3 个相关标签语境合适时优先复用既有标签回写标签直接写入已发布文档的tags字段。结果内容创作者无需手动操作即可获得一致、相关的标签显著提升内容组织效率与可发现性。自定义扩展调整标签生成规则修改instruction指令即可改变打标行为。例如生成 5 个标签并使用 camelCaseinstruction: Based on the $content, create 5 relevant tags instead of 3. Focus on technical topics and use camelCase format.更换目标字段将回写路径从tags改为其他字段target: { path: categories, // Instead of tags }面向不同文档类型修改蓝图中的过滤条件即可适配其他内容类型。例如针对article类型、且keywords字段为空时触发filter: _type article !defined(keywords) delta::changedAny(content)结合 auto-summary 示例 的对比可以看出client.agent.action.generate是 Sanity Agent Actions 的通用能力——同一套instructionParams/target/forcePublishedWrite机制既能生成标签也能生成摘要、语气分析等auto-tag 只是其中一种典型用法。小结auto-tag 展示了 Sanity Functions 与 Agent Actions 组合的典型模式用蓝图声明事件驱动函数、用 GROQ 动态取数补充上下文、用 AI 指令生成结构化结果并自动回写文档。围绕 README.md、index.ts 与 package.json 三份文件你可以快速复刻这套自动打标签能力并推广到自动摘要、自动重定向、自动分类等更多编辑自动化场景。【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Sanity Auto-Tag 函数实战：基于 AI 的博客文章自动打标签全流程指南
Sanity Auto-Tag 函数实战基于 AI 的博客文章自动打标签全流程指南【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity本文以 Sanity 仓库中的 auto-tag 函数示例 为核心完整讲解如何借助 Sanity Functions 与 Agent Actions在博客文章发布时自动生成 3 个相关标签并复用既有标签维持词表一致。读完本文你将掌握从 schema 字段定义、蓝图Blueprint配置、本地测试到生产部署的完整链路并能基于源码自由定制标签数量、目标字段与触发过滤条件。背景与解决的问题在传统编辑流程中内容创作者需要手动为每篇博客文章打标签。这种做法不仅耗时每篇约 2-3 分钟还容易导致整个内容库中标签命名不一致——有人写javascript有人写JavaScript还有人写js最终削弱了内容的可发现性与组织质量。auto-tag 这个 Sanity Function 的目标就是解决这个问题自动触发文章创建或内容字段更新时自动执行无需人工介入AI 分析基于文章content字段的正文内容利用 Sanity 的 AI 能力生成语义相关的标签词表一致性生成标签前会查询其他已发布文章使用过的标签优先复用已有标签避免词表无限膨胀自动回写将生成的标签直接写回文档的tags数组字段发布即可用。从源码看这个示例的核心实现在 examples/functions/auto-tag/index.ts依赖sanity/client与sanity/functions两个包见 package.json。前置要求在开始之前请确认满足以下条件一个启用了 Functions 能力的 Sanity 项目schema 中包含post文档类型且具备content字段Portable Text 富文本类型用于内容分析tags数组字段用于存储生成的标签可访问 Sanity 的 AI 能力Agent Actions 功能本地开发环境使用Node.js v22.x与生产运行时保持一致Sanity CLI 版本v3.92.0 或以上部署时需要。该函数与 Sanity 官方 clean 系列模板兼容。官方推荐先在本地安装任意 clean 模板后在模板项目中试用本函数。为 schema 添加 tags 字段如果使用nextjs-clean模板需要先在studio/src/schemaTypes/documents/post.ts中给fields数组添加如下字段defineField({ name: tags, title: Tags, type: array, of: [{ type: string }], description: Tags will be automatically generated when you publish a post, }),然后在/studio目录下部署更新后的 schema# /studio npx sanity schema deploy函数实现原理先看核心实现 examples/functions/auto-tag/index.ts 的完整逻辑import {createClient} from sanity/client import {documentEventHandler} from sanity/functions export const handler documentEventHandler(async ({context, event}) { const client createClient({ ...context.clientOptions, apiVersion: vX, useCdn: false, }) const {data} event const {local} context // local is true when running locally try { const result await client.agent.action.generate({ noWrite: local ? true : false, // if local is true, we dont want to write to the document, just return the result for logging instructionParams: { content: { type: field, path: content, }, tagsUsedInOtherPosts: { type: groq, query: array::unique(*[_type post _id ! $id defined(tags)].tags[]), params: { id: data._id, }, }, }, instruction: Based on the $content, create 3 relevant tags. Attempt to use $tagsUsedInOtherPosts first if they fit the context. Tags should be simple lowercase words strings and no brackets., target: { path: tags, }, documentId: data._id, schemaId: _.schemas.default, forcePublishedWrite: true, }) console.log( local ? Generated tags (LOCAL TEST MODE - Content Lake not updated): : Generated tags:, result.tags, ) } catch (error) { console.error(Error occurred during tag generation:, error) } })关键参数逐项解读context.clientOptions由 Sanity Functions 运行时注入的客户端配置这里基于它创建了一个apiVersion: vX、useCdn: false的客户端。useCdn: false很关键——AI 回写与读取都要求实时数据不能走 CDN 缓存。noWrite本地测试时置为trueAI 只返回生成结果、不写入 Content Lake生产环境置为false才会真正落盘。源码注释明确写了这一点。instructionParams.contenttype: field表示从文档的content字段直接取正文内容作为$content变量注入指令。instructionParams.tagsUsedInOtherPoststype: groq表示通过一段 GROQ 查询动态取数。这条查询array::unique(*[_type post _id ! $id defined(tags)].tags[])的含义是收集所有_type post、ID 不等于当前文档、且已定义tags的文档的全部标签再经array::unique去重——这正是复用既有标签、维持词表一致的实现来源。当前文档 ID 通过params.id传入避免把自己的标签也算进去。instructionAI 指令模板告诉模型基于$content创建 3 个相关标签如果$tagsUsedInOtherPosts中的标签符合语境则优先使用标签应为简单的小写单词字符串不要带括号。target.pathAI 生成结果的回写路径这里是tags字段。documentId目标文档 ID来自事件的data._id。schemaId: _.schemas.default目标 schema 标识。forcePublishedWrite: true强制写入已发布版本确保标签立即可见。函数将生成结果打印到日志本地模式会明确提示 Content Lake 未更新出错时捕获并打印错误不会导致事件链路崩溃。蓝图配置与部署步骤重要提示以下命令需要在项目根目录执行不要进入studio/目录。1. 初始化示例如果你还没有初始化 blueprints先执行npx sanity blueprints init期间会提示选择你的组织organization和 Sanity studio。然后添加 auto-tag 示例npx sanity blueprints add function --example auto-tag2. 将函数加入蓝图配置在项目根目录的sanity.blueprint.ts中注册该文档函数// sanity.blueprint.ts import {defineBlueprint, defineDocumentFunction} from sanity/blueprints export default defineBlueprint({ resources: [ defineDocumentFunction({ name: auto-tag, src: ./functions/auto-tag, memory: 2, timeout: 30, event: { on: [create, update], filter: _type post (delta::changedAny(content) || (delta::operation() create defined(content))), projection: {_id}, }, }), ], })各配置项的含义name函数名称本地测试与部署时以此引用src函数源码目录相对于项目根目录memory分配给函数的内存GB示例为 2timeout函数超时时间秒示例为 30event.on触发事件类型create/update表示文档创建与更新时触发event.filter触发过滤条件仅当_type post且满足content字段发生变更或文档刚创建且content已定义时才执行避免无关更新白白消耗 AI 调用event.projection注入事件负载的字段投影这里只取{_id}即可满足实现所需。这一配置在示例的 package.json 中也有对应声明blueprintResourceItem字段且 examples/sanity.blueprint.ts 会遍历functions/目录自动发现并注册所有函数示例可作为理解配置格式的参考。3. 安装依赖在项目根目录执行npm install函数运行所需的依赖为sanity/client^8.6.1与sanity/functions^1.7.2版本以 package.json 为准。4. 确保 schema 已部署进入 studio 目录执行# In the studio/ folder npx sanity schema deploy本地测试函数生产部署前务必先在本地验证函数行为。简单测试命令使用数据集中的真实文档 ID 测试npx sanity functions test auto-tag --document-id insert-document-id --dataset production --with-user-token将insert-document-id替换为数据集中的实际文档 IDproduction替换为你的数据集名称。交互式开发模式启动开发服务器进行交互式测试npx sanity functions dev测试建议使用真实文档 ID文档函数要求 ID 在数据集中真实存在本地使用 Node.js v22.x与生产运行时保持一致覆盖边界场景测试无内容、或已带标签的文章查看 CLI 日志函数日志会输出在 CLI 中用于排查问题先关掉 AI 写入可在函数中临时设置noWrite: true先验证分析流程准备测试内容如果没有未打标签的文章先创建一些测试文档。生产部署本地测试通过后即可部署。注意部署前请确认你的账户拥有该项目的 Deploy Studio 权限。部署前置条件Sanity CLI v3.92.0 或以上项目的 Deploy Studio 权限Node.js v22.x匹配生产运行时。部署步骤核对蓝图配置确认sanity.blueprint.ts已正确配置 auto-tag 函数见上文配置代码。部署蓝图在项目根目录执行npx sanity blueprints deploy该命令会依次完成打包你的函数代码上传到 Sanity 的基础设施配置文章发布相关的事件触发器让 auto-tag 函数在生产环境生效。验证部署结果部署完成后可通过以下方式确认在 Sanity Manage 控制台的 API Functions 下查看函数状态发布一篇没有标签的新文章确认标签被自动生成在 CLI 中监控函数日志。部署最佳实践先充分本地测试任何改动都应先在本地验证再部署监控 AI 用量Agent Actions 有使用额度与成本可到 Manage 控制台的 Settings 查看详情避免递归触发过滤条件中通过!defined(tags)之类的判断防止函数给文档写完标签后再次触发自身使用精确的过滤条件当前 filter 只针对没有标签的 post避免不必要的执行开销。常见故障排查错误Deploy Studio permission required原因当前账户没有该项目的部署权限解决请项目管理员为你授予 Deploy Studio 权限。部署后函数没有生成标签原因文章可能已有标签或 schema 字段配置不正确解决改用没有既有标签的文章测试并确认tags字段已存在于 schema 中。运行流程全景当编辑发布一篇未打标签的新博客文章时整个流程如下触发文档 create/update 事件命中过滤条件content字段变更分析函数读取文章的content字段交给 AI 分析取词通过 GROQ 查询收集其他已发布文章的既有标签用于词表对齐生成AI 生成 3 个相关标签语境合适时优先复用既有标签回写标签直接写入已发布文档的tags字段。结果内容创作者无需手动操作即可获得一致、相关的标签显著提升内容组织效率与可发现性。自定义扩展调整标签生成规则修改instruction指令即可改变打标行为。例如生成 5 个标签并使用 camelCaseinstruction: Based on the $content, create 5 relevant tags instead of 3. Focus on technical topics and use camelCase format.更换目标字段将回写路径从tags改为其他字段target: { path: categories, // Instead of tags }面向不同文档类型修改蓝图中的过滤条件即可适配其他内容类型。例如针对article类型、且keywords字段为空时触发filter: _type article !defined(keywords) delta::changedAny(content)结合 auto-summary 示例 的对比可以看出client.agent.action.generate是 Sanity Agent Actions 的通用能力——同一套instructionParams/target/forcePublishedWrite机制既能生成标签也能生成摘要、语气分析等auto-tag 只是其中一种典型用法。小结auto-tag 展示了 Sanity Functions 与 Agent Actions 组合的典型模式用蓝图声明事件驱动函数、用 GROQ 动态取数补充上下文、用 AI 指令生成结构化结果并自动回写文档。围绕 README.md、index.ts 与 package.json 三份文件你可以快速复刻这套自动打标签能力并推广到自动摘要、自动重定向、自动分类等更多编辑自动化场景。【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考