设备手册别再当附件发：TechArticle 与 proficiencyLevel 的文档中心架构

设备手册别再当附件发TechArticle 与 proficiencyLevel 的文档中心架构适用读者负责设备厂商官网、售后知识库的工程师与架构师适用读者正在把产品说明书、维保手册从 PDF 附件迁到网页的人适用读者关心自家文档能不能被 AI 搜索引用的技术负责人九月初接了个空压机厂商的活儿甲方姓周技术部经理。他甩过来一句话我记到现在「我们手册做得可认真了两百余页全彩印刷怎么客户问 AIAI 给的答案里压根没有我们」我让他把官网手册栏目打开看了一眼——三十多个 PDF最大的一个 48MB挂在「资料下载」下面点进去直接浏览器下载。这事儿说白了就是你把最值钱的技术内容锁在 AI 爬虫AI Crawler啃不动的容器里还指望别人引用你白费劲。这篇写的是我们后来的改法把手册从 PDF 附件改成可抓取的 HTML 文档页用 schema.org 的 TechArticle 加上 proficiencyLevel、dependencies、articleSection 这几个字段做结构化描述.NET 8 服务端渲染一套模板批量出页。两个月跑下来自建监测口径下主流 AI 搜索引擎对我们文档页的引用条数从 0 涨到了两位数。生成式引擎优化Generative Engine Optimization, GEO这件事在制造业 B2B 场景里落地起来其实没有多少玄学主要靠架构选对。PDF 附件模式到底卡在哪先讲清楚问题再讲方案。PDF 对 AI 搜索不友好卡点有四个抓取成本高。48MB 的 PDF爬虫要解析文本层、处理分栏和表格很多 AI 爬虫对大文件直接设了体积上限。结构信息全丢。PDF 里的「3.2.1 更换滤芯」到了纯文本层就成了一行字层级、步骤、警告框这些语义全没了。没有元数据。AI 引擎判断「这段内容是给谁看的、需要什么前置技能」PDF 给不出任何线索。引用粒度太粗。AI 引用网页时可以精确到一个锚点小节引用 PDF 时基本只能整个文件丢给用户体验差被选中的概率自然低。周经理的团队之前不是没试过他们让外包把三本手册转成了网页结果转出来是整页大图配 JS 翻页插件服务端渲染Server-Side Rendering, SSR基本没有爬虫拿到的 HTML 里正文是空的。等于钱花了事没成。把上面四个卡点摊开跟 HTML 文档页模式放在一起看更直观维度PDF 附件模式HTML 文档页模式抓取成本高。48MB 体积上限爬虫要解析文本层、处理分栏和表格大文件常被直接拒抓低。纯文本 HTML 轻量可抓正文随页面直达结构保留全丢。「3.2.1 更换滤芯」到纯文本层成一行字层级、步骤、警告框语义全没完整。标题层级、步骤、警告框以语义化标签保留元数据无。AI 判断「给谁看、要什么前置技能」拿不到任何线索有。TechArticle proficiencyLevel / dependencies / articleSection 结构化输出引用粒度粗。基本只能整个文件丢给用户体验差细。可精确到小节锚点回答能落到具体一步AI 引用概率低。上线前自建监测口径下引用数为 0高。两个月后引用从 0 涨到两位数小节锚点占七成传统 SEO 收益弱。PDF 下载页自然搜索进站少强。文档页自然搜索进站比 PDF 下载页翻了三倍不止文档中心站点架构三层分工我们的方案是单独起一个 docs 子域跟主站解耦。架构分三层Pandoc/手工Markdown 源库元数据管道解析补齐校验.NET 8 文档站Razor SSR JSON-LD 模板静态化 HTML 输出docs.example.com传统搜索引擎AI 爬虫与 AI 搜索Sitemap 索引 now API内容源层手册正文统一收成 Markdown进 Git 仓库管版本。老工程师用 Word 写了十几年的习惯改不动就保留 Word配一个 Pandoc 转换脚本进库。元数据管道这是后面重点手册的设备型号、适用人群、前置条件这些字段都是从这里补出来的。输出层.NET 8 文档站负责服务端渲染每篇文章输出带 JSON-LD 的完整 HTML同时生成 sitemap内容更新后通过索引推送接口主动通知搜索端。为什么不直接在主站 CMS 里发因为手册的元数据模型型号、版本、技能等级跟新闻、产品页完全是两套硬塞进通用 CMS后面每一步都要绕。docs 子域还能单独配爬虫策略和缓存策略省事。元数据从哪来三层来源拼接手册页要变成 AI 能理解的东西光有正文不够得有结构化的「说明书元数据」。我们的字段来源分三层用一张表说清楚字段主要来源补齐方式校验规则设备型号文件命名规范管道正则提取抽不到人工补必须匹配产品库已有 SKU适用人群手册前言原文LLM 初筛 编辑确认枚举操作工/维保技工/电气工程师前置技能维保章节分析技能字典匹配引用技能字典 ID防自由发挥文档类型目录树归类归类映射表安装/操作/维保/故障四类版本号Git tag自动继承语义化版本强制递增这里有个细节值得说。管道里第一版我们放了个 LLM 自动分类跑了两周发现「故障排查」和「维保」混着分错分类率接近两成。后来改成 LLM 只做初筛建议、编辑在后台点确认错误率降到 3% 以下人也轻松了——因为候选答案已经给出来了点一下就行。流程上是这样串的文档站编辑后台元数据管道Git 仓库文档站编辑后台元数据管道Git 仓库push 手册 Markdown解析型号/章节/版本生成待确认工单确认 proficiencyLevel 等字段写入元数据库并触发渲染SSR 输出 HTML JSON-LDTechArticle 的三个关键字段别都用默认值schema.org 的 TechArticle 类型自带几个面向「技术内容」的字段很多站点直接空着不用我觉得这是最可惜的地方。AI 搜索引擎在决定「引用谁、引用哪段」时这些字段就是它判断内容匹配度的抓手——这个词在这儿是中性的就是「抓手」不是黑话。字段我们怎么填对 AI 引用的影响proficiencyLevelBeginner / Expert 五档枚举决定 AI 推荐给哪类提问者新手问题不会引到维保级文档dependencies前置操作文档的 URL 列表AI 回答复杂问题时会沿链取多篇而不是断章取义articleSection章节 URL 标题给 AI 提供「引用到小节」的锚点回答可以精确到一步proficiencyLevel 特别想多说两句。空压机手册里「日常检查」和「主机大修」是两篇文档受众完全不同。以前 PDF 时代这两篇长得差不多AI 分不清。我们把前者标 Beginner后者标 Expert并且在正文开头放一句明示「本文面向持证维保人员日常巡检请看另一篇」。九月改完十月中我们抓 AI 搜索的回答日志自建监测口径每天对二十个典型问题手工提问并记录引用来源发现「空压机异响怎么办」这类新手问题开始稳定引用日常检查那篇而大修文档只在专业问法下出现。受众分流起效了。dependencies 的用法也顺带提一下维保文档的 dependencies 里挂上「断电操作规程」的链接AI 组织回答时经常把两篇内容拼在一起给出这对用户是加分的对引用方就是我们等于多占了一处来源位。模板怎么渲染一份 JSON-LD 模板服务四类文档输出层是 ASP.NET Core 8Razor 做服务端渲染JSON-LD 从一个模板服务里统一生成。环境.NET 8 / C# 12无第三方依赖。// TechArticleJsonLdBuilder.cs — 统一生成 TechArticle 结构化数据// 环境.NET 8 / C# 12 / Newtonsoft.Json 13无其他第三方依赖publicsealedclassTechArticleJsonLdBuilder{privatereadonlyISkuCatalog_sku;// 产品库校验型号真伪publicJObjectBuild(DocMetameta,IReadOnlyListSectionsections){// 型号必须能在产品库里找到找不到直接抛错不让脏数据上线_sku.MustExist(meta.Sku);varjsonnewJObject{[context]https://schema.org,[type]TechArticle,// proficiencyLevel 用五档枚举别自己发明字符串// AI 引擎靠它分流受众新手问法会压低 Expert 级文档权重[proficiencyLevel]meta.Levelswitch{DocLevel.OperatorBeginner,DocLevel.MaintainerIntermediate,DocLevel.ElectricalExpert,// 兜底给 Beginner宁可保守也别误导新手_Beginner},// 前置文档全量 URLAI 会沿着链路取多篇拼接回答[dependencies]newJArray(meta.PrereqUrls),// 章节锚点 URLAI 引用可以落到具体小节而不是整篇[articleSection]newJArray(sections.Select(snewJObject{[name]s.Title,[url]$https://docs.example.com/{meta.Slug}#{s.Anchor}})),// 作者统一挂组织不写个人避免人员变动导致署名失效[author]newJObject{[type]Organization,[name]meta.BrandName}};// 返回后由 Razor 模板塞进 script typeapplication/ldjsonreturnjson;}}上线前我们还有一个 CI 自检脚本专门防 JSON-LD 低级错误# 环境Linux CI / curl 8.x —— 文档页上线前三项自检# 这三项全是血的教训换来的JSON-LD 少个括号我们曾三天没发现# 第一项确认 HTML 里真的输出了 JSON-LD期望输出 1curl-shttps://docs.example.com/docs/ktr-120/2.3/maintenance|grep-capplication/ldjson# 第二项确认老版本路径 301 到当前版期望输出 301curl-s-o/dev/null-w%{http_code}https://docs.example.com/docs/ktr-120/2.1/maintenance# 第三项确认 sitemap 收录了新版 URL期望输出 1curl-shttps://docs.example.com/sitemap.xml|grep-cktr-120/2.3/maintenance# 三项任一不符合预期流水线直接标红拦下不允许人工放行页面渲染时把这个 JObject 直接塞进script typeapplication/ldjson同一份数据也用于面包屑和 Open Graph保证页面上各处信息一致。校验用 Schema.org 官方的验证工具跑一遍再上线别信自己手写的 JSON 没毛病——我们第一次上线时 dependencies 少了个中括号愣是三天后才被抓出来。性能与边界条件也值得单独说。文档量上去之后SSR 的响应时间会明显变长我们压测过文档数在 500 篇以内时单页 SSR 响应基本稳定在 80ms 上下一旦超过 500 篇Razor 每次都要重新解析模板、拼 JSON-LD、渲染整页 HTML响应时间会涨到 300ms 以上爬虫批量抓取时很容易把 CPU 打满。我们的做法是两层兜底一是给 Razor 页面开输出缓存[ResponseCache]按 URL 版本号做 key命中直接返回静态字节二是对不常改的文档走静态化预生成——构建时把 HTML 一次性落盘线上只做文件服务SSR 只留给真正需要动态渲染的页面。这样 500 篇和 5000 篇的响应时间基本拉平。JSON-LD 生成还有一个边界要处理SKU 校验失败。TechArticleJsonLdBuilder里_sku.MustExist(meta.Sku)是直接抛异常的这在单篇手工发布时没问题但批量管道里一篇脏数据抛异常会把整批渲染全卡住。我们后来改成降级策略校验失败时跳过该文档、不输出 JSON-LD同时把型号、来源文件、失败原因写进日志汇总到编辑后台的待办列表里人工处理。宁可这一篇暂时没有结构化数据也不能让一批文档因为一篇脏数据集体下线。版本怎么管URL 带版本老版本 301手册是会改版的。2.1 版的维保周期跟 2.3 版不一样这种内容 AI 引用了旧版是要出安全事故的。我们的规则简单粗暴URL 永远带版本/docs/ktr-120/2.3/maintenance无版本的路径 301 到当前版。非当前版本页加noindexJSON-LD 里照常输出但 sitemap 不收录。版本页头部放变更摘要AI 爬虫拿到的正文第一屏就是「本版改了什么」。周经理原话「以前客户拿 2.1 的手册来投诉我们售后都不知道他看的是哪版。现在 URL 一看就知道。」这算是顺带把售后的老毛病也治了。底层机制AI 引擎拿到这些字段后干了什么原理这一节讲讲我自己的理解不一定对但跟观测结果对得上。AI 搜索的检索链路大概是这样爬虫抓页 → 抽取正文与结构化数据 → 切块并向量化 → 用户提问时先粗排召回、再按「问题-受众-粒度」匹配精排。TechArticle 的字段其实在两个环节起作用。切块环节articleSection 的锚点让切块器有天然的分界线。没有它切块只能按 token 数硬切「更换滤芯」的步骤三可能跟步骤七落在同一块里AI 引用出来就是一锅粥。有锚点切块每块自成一个完整操作单元引用时可以整块搬走。精排环节proficiencyLevel 和 dependencies 相当于给内容打了「受众标签」和「上下文标签」。用户问「空压机报警 E03 怎么处理」这是个新手问法精排会压低 Expert 级文档的权重问「E03 报警下做绝缘测试的合规流程」就轮到 Expert 级上。GEO 圈里天天说「内容要可引用」落到工程上可引用就是切块粒度对 受众标签对没有更多秘密。还有一层常被忽略AI 引擎对自相矛盾的内容同站两个版本说法不一会整体降权。版本管理那套规则不只是给用户看的更是给 AI 看的一致性声明。上线两个月的观察数据口径先说死以下全部是我们自建监测口径——每天固定二十个典型客户问题对三家主流 AI 搜索产品手工提问记录是否引用 docs 子域、引用到哪一节。不是任何第三方统计样本小看趋势别抠单日数字。指标9 月初PDF 期11 月中文档页上线两个月被引用文档数017 篇单日最多引用次数011 次引用粒度无小节锚点占七成新手类问题命中09 个问题稳定命中另外有个意外收获传统搜索引擎那边文档页的自然搜索进站比 PDF 下载页翻了三倍不止。结构化这一套对传统 SEO 也是顺手的红利不只是给 GEO 做的。还没解决的问题别以为这是一篇成功学。三个坑现在还开着Word 转 Markdown 的表格还原还是半手工复杂管网图转出来直接废这部分内容暂时保留 PDF 双轨。AI 引用没有回传通知我们只能靠手工监测猜。哪天有引擎愿意做引用上报的开放接口这行当会好干很多。多语言手册的 proficiencyLevel 翻译口径还没统一英文站目前沿用的还是中文五档硬翻效果未验证。文档中心这个方向我的判断是制造业 B2B 迟早都得走客户问 AI 的比例只会涨PDF 附件模式的占比只会跌。早改早受益晚改就是看着别家被引用。参考与延伸schema.org TechArticle 类型定义Google 搜索中心结构化数据标记指南web.dev结构化数据与搜索体验MDNJSON-LD 与 SEO 实践GEO · AI搜索 · TechArticle · proficiencyLevel · JSON-LD · Schema.org · 设备手册数字化