企业官网建设流程全解析

开发者布道师（Developer Advocate）在很多技术公司的组织架构里，曾经是一个投入产出很难量化的岗位。它介于研发、产品、市场和社区之间，核心任务是把 SDK、API 和开源项目的能力翻译成开发者能直接理解的文档、示例代码和最佳实践，再把开发者反馈翻译回产品团队。这个角色在云服务扩张、开源生态爆发和前端技术快速迭代的周期里非常有效。不过过去两年，一个明显变化正在发生：开发者获取技术信息的方式，正在从“搜文档、看博客、问布道师”迁移到“在 IDE 里直接问 AI 助手”，而企业内部的知识库、示例代码和 FAQ 也开始改用 RAG、代码生成流水线和自动化验证来承接。于是出现了两种判断：一种认为开发者布道师会消亡，另一种认为布道师必须进化成 AI Engineer。这篇文章从工程视角拆解这场角色迁移：布道师过去到底交付了什么，哪些工作正在被 AI 工程化取代，AI Engineer 具体接替了什么，以及仍然在做布道相关工作的人如何完成一次可落地的技术转型。

1. 布道师过去真正交付的是三层能力

1.1 三层能力：内容生产、内容分发、反馈闭环

先把布道师的日常工作还原出来，再判断哪些环节会被取代。把一家技术公司对外输出的能力摊开，布道师通常承担三层工作。第一层是内容生产，包括 SDK 快速上手、API 代码示例、框架集成教程、故障排查指南、迁移说明。这类工作以代码为主，数量大、同质化高，需要不断跟随版本更新。第二层是内容分发，包括技术分享、大会演讲、社区文章、开源项目运营、生态合作。它依赖个人的表达能力和行业信任。第三层是反馈闭环，布道师要把社区里的高频提问、反复踩坑、接口不好用的部分归纳成产品需求，推动 SDK、产品或文档团队改进。

从技术链路看，布道师实际上是一个人工翻译层：产品能力先翻译给布道师，布道师再翻译给开发者。过去开发者没有更低成本的翻译渠道，所以这个角色在信息链路上拥有不小的定价权。布道师说某个坑在哪个版本修复，开发者通常会照做。这个结构现在正在被改写，原因是开发者身边出现了新的翻译层，也就是大模型。

1.2 最容易受 AI 冲击的工作，恰好是代码量最大的工作

按受冲击程度排序，最容易被替代的是常规答疑、代码示例生成、文档迁移和入门教程编写。原因不是模型写得比布道师更好，而是模型响应更快、成本更低、能根据提问者上下文反复调整答案。一个开发者把报错信息粘进 IDE 助手，几秒内就能得到一段可运行代码，这种体验已经逼近布道师手把手支持的效率。

相对难替代的是需要线下信任和长期关系的部分，比如关键客户的技术护航、行业会议上的深度分享、开源社区的治理协调。这类工作的交易对象不是信息，而是信任。但是在企业预算收紧的周期里，容易被量化的内容生产岗位会先承受压力，而那些无法被量化的信任工作又往往被要求更快地转化成可见指标。理解这个压力，是理解“开发者布道师消亡”讨论的前提。

1.3 一个容易被忽略的事实：布道师最重要的资产是踩坑语料

布道师过去十几年积累下来的真正资产，不是某几篇爆款文章，而是大量的一手踩坑语料。比如：某个 SDK 在特定 Python 版本下证书验证失败、某个 API 的默认分页大小会导致性能问题、某个鉴权方式的过期时间很难调试。这些信息散落在聊天记录、Issue 和口头经验里，没有结构化，也没有进入任何系统。

这些语料恰恰是大模型时代最值钱的东西。RAG 系统的回答质量取决于检索库里的数据质量，评测集的构造也依赖真实问题样本。布道师若能把零散的踩坑信息整理成结构化文档、问题和答案，就相当于把一个隐形的个人经验库改造成团队可复用的 AI 知识库。这是后面所有转型动作的基础。

2. AI 工程化先从消费方式开始瓦解翻译层

2.1 文档的消费者从人扩展到了模型

以前文档是写给人读的。开发者打开官网，按目录一层层阅读，遇到问题再翻 FAQ。现在文档的消费者不只是人，还有大模型。IDE 助手、对话机器人、内部知识库系统都会读取仓库里的 README、官方文档、示例代码和 Issue，再基于这些内容生成答案。这个变化带来一个实际后果：文档如果结构混乱、示例不能运行、参数命名前后不一致，人还可以靠经验跳过，模型却会把这些内容当成事实输出，造成错误被放量传播。

这也是为什么越来越多技术团队开始强调文档的机器可读性。统一的 Markdown 结构、稳定的标题锚点、可验证的代码块、规范的 front matter 元数据，目的是让文档既能给开发者看，也能被检索系统稳定地切分和引用。布道师过去更擅长讲场景、讲故事，现在必须补上结构化输出和数据治理这一课。

2.2 RAG 让“去问产品”变成“去问知识库”

RAG（Retrieval-Augmented Generation，检索增强生成）是目前最常见的知识型 AI 应用架构。它先把产品文档、FAQ、Issue 处理记录切成文本块，用 embedding 模型转成向量并写入向量数据库；开发者提问时，系统把问题转成向量，通过相似度检索拿到最相关的文档块，再交给大模型生成回答。相比直接靠模型记忆，RAG 的回答能引用原文，也容易在文档更新后立刻生效。

下面是一个最小演示，用 OpenAI 兼容接口实现一个面向 SDK 的文档问答助手。实际项目里可以替换成任意 embedding 和 chat 模型，关键流程不变。把这段代码保存为doc_assistant.py，后面评测示例会直接引用它。

import os import numpy as np from openai import OpenAI client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) DOCS = [ { "id": "sdk-timeout", "content": "SDK 默认超时时间为 5 秒，可以在客户端构造参数中传入 timeout 字段调整。生产环境建议同时配置重试次数。", }, { "id": "sdk-env-key", "content": "密钥通过环境变量注入，例如 API_KEY=xxx python app.py。不要把密钥写进代码或提交到仓库。", }, { "id": "sdk-error-401", "content": "返回 401 说明凭证无效。先检查环境变量是否加载，再检查 token 是否过期，最后检查系统时钟是否偏移。", }, ] def embed(text: str) -> np.ndarray: resp = client.embeddings.create(model="text-embedding-3-small", input=text) return np.array(resp.data[0].embedding) def normalize(vec: np.ndarray) -> np.ndarray: return vec / (np.linalg.norm(vec) + 1e-9) def search(query: str, docs: list, top_k: int = 2) -> list: q = normalize(embed(query)) scored = [] for d in docs: if "vector" not in d: d["vector"] = normalize(embed(d["content"])) score = float(np.dot(q, d["vector"])) scored.append((score, d)) scored.sort(key=lambda x: x[0], reverse=True) return [d for _, d in scored[:top_k]] def answer(query: str) -> str: candidates = search(query, DOCS) context = "\n\n".join(d["content"] for d in candidates) prompt = ( "你是 SDK 技术支持助手。只基于下方资料回答，资料不足时明确说缺少信息。\n\n" f"资料：\n{context}\n\n问题：{query}" ) resp = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "你是严谨的技术文档助手，回答要简洁、可验证。"}, {"role": "user", "content": prompt}, ], temperature=0.2, ) return resp.choices[0].message.content if __name__ == "__main__": print(answer("为什么请求接口一直返回 401？"))

运行之前要安装依赖：pip install openai numpy，并配置OPENAI_API_KEY环境变量。这个示例做了三个关键动作：将文档切块后向量化、计算余弦相似度取 Top-K、把检索结果拼进提示词交给对话模型。它把布道师日常处理的高频 FAQ 工作自动化了。布道师不再需要逐条回答重复问题，而是把精力转移到维护文档块质量、补充边界案例和设计评估集上。

注意：上面示例适合学习环境和内部原型。生产环境至少还要补充密钥管理、日志追踪、接口限流、敏感信息过滤，以及模型输出与原文不一致时的回退策略。

2.3 示例代码从手写维护变成生成、验证、发布流水线

布道师过去大量时间消耗在写示例代码和确保示例能跑通。现在这项工作可以拆成三个环节：生成、验证、发布。生成可以交给大模型完成，但验证必须由工程化的流水线负责。没有验证的模型生成代码，本质上是在制造一种更新更快的错误文档。

下面是一个 GitHub Actions 示例，让文档里的 Python 代码块在每次合并前自动运行。这一步意义很大：模型生成、AI 辅助改写、人工手写的示例代码全部纳入同样的质量门槛。

name: validate-doc-snippets on: push: paths: - "docs/**" pull_request: paths: - "docs/**" jobs: validate: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.11" - name: Validate Python snippets run: python scripts/validate_snippets.py docs/

配套的校验脚本如下。

import re import subprocess import sys import tempfile from pathlib import Path def extract_python_snippets(md_path: Path): text = md_path.read_text(encoding="utf-8") pattern = re.compile(r"```python\n(.*?)```", re.DOTALL) return pattern.findall(text) def run_snippet(code: str): with tempfile.NamedTemporaryFile("w", suffix=".py", delete=False) as f: f.write(code) tmp = f.name try: return subprocess.run( [sys.executable, tmp], capture_output=True, text=True, timeout=30 ) finally: Path(tmp).unlink(missing_ok=True) def main(doc_dir: str): failed = False for md in Path(doc_dir).rglob("*.md"): for i, code in enumerate(extract_python_snippets(md)): proc = run_snippet(code) if proc.returncode != 0: failed = True print(f"[FAIL] {md}: 第 {i + 1} 个 python 代码块") print(proc.stderr[-2000:]) else: print(f"[ OK ] {md}: 第 {i + 1} 个 python 代码块") sys.exit(1 if failed else 0) if __name__ == "__main__": main(sys.argv[1])

文档里的代码块不一定都能直接运行，比如它可能依赖真实服务、数据库或外部账号。实际项目中要给校验脚本注入 mock 数据、临时目录和测试环境变量，并把这类条件在文档的 front matter 里声明清楚，避免 CI 因为环境依赖持续报错。

3. AI Engineer 接替的不是头衔，而是反馈闭环

3.1 AI Engineer 的职责和技术栈

AI Engineer 不是提示词工程师。完整意义上的 AI Engineer 要处理模型与数据、系统架构、评估回归、成本和安全四类问题。放在开发者工具场景里，对应的工作就是回答下面这些问题：代码补全和问答应该选哪个模型；文档知识库的切分、向量化和检索链路怎么搭；示例代码生成之后如何判断准确率；模型输出的幻觉怎么拦截；一次提问的成本和延迟是否在可接受范围。

举个例子，一套给开发者使用的文档问答系统，AI Engineer 要做的不是只写一个调用模型的函数。他需要先分析开发者提问的分布，确定哪些问题应该由精确检索兜底，哪些问题允许模型发挥；再设计文本切分策略，避免把多个主题塞进一个块；还要在回答里附带原文引用，方便开发者追溯。系统上线之后，还要看指标：检索命中率、提问后是否继续追问、回答中是否出现版本号错误。一个完整的 AI Engineer 不是模型的用户，而是模型的工程化运营者。

AI Engineer 的日常技术栈至少包含以下内容：Python 工程能力、向量数据库使用、Embedding 模型调用、RAG 链路设计、评测集构造、函数调用和 Agent 编排、日志与可观测、以及基本的模型成本管理。很多内容并不需要从头训练模型，而是把现有模型、开源组件和业务数据组装成一个稳定、可评估、可维护的系统。

3.2 布道师的旧技能如何迁移到新岗位

布道师积累的能力并没有作废，但需要重新组装。写作能力迁移为评测集设计能力。布道师最清楚哪些案例容易讲错，也最清楚用户会怎么提问，这些恰好构成评测集的内容。演示能力迁移为原型开发能力。过去要做 PPT 和 Demo 给几十个人看，今天可以做一个 AI 原生小工具给几千个人用。社区影响力迁移为数据飞轮。社区里的提问和踩坑记录，是构造 RAG 文档库和评测集的原始语料。

这一轮迁移的真正含义是：布道师原有的领域判断力依然值钱，值钱的部分从直接服务开发者，变成定义“什么样的 AI 服务对开发者才算合格”。

4. 一个人也能搭的 AI 布道最小系统

4.1 场景拆解：把入门教程改造成知识库

假设你负责一个云存储 SDK 的开发者支持工作。过去的工作流是写一篇五分钟上手教程，然后等待邮件和 Issue。现在可以把它改造成一个最小系统。第一步，把教程、FAQ、Issue 记录整理成结构化 Markdown。第二步，写离线任务做文本切分和向量化。第三步，搭建一个问答服务，按 2.2 的方式响应开发者提问。第四步，给示例代码加 CI 验证。第五步，收集漏答和答错问题，倒推文档改进。这五步就是布道工作 AI 改造的最小闭环。

4.2 评测集：把“答得好不好”变成可量化指标

没有评测集的 AI 问答系统，只能演示，不能上线。评测集的价值是把布道师的主观经验变成客观门槛。构造评测集的原则是：每条记录包含真实问题、正确答案关键词、关联文档和期望行为。下面是示例结构。

[ { "question": "SDK 默认超时是多少？", "expected_keywords": ["5 秒"], "related_doc": "sdk_config.md" }, { "question": "认证返回 401 应该怎么排查？", "expected_keywords": ["环境变量", "token", "时钟"], "related_doc": "sdk_error_401.md" } ]

对回答质量的判断可以先从关键词命中开始，后续再升级为模型评分和人工抽检。下面是一个极简的评测运行方式，它假设answer函数来自前面保存的doc_assistant.py。

# 假设 doc_assistant.py 里已有前面实现的 answer 函数 from doc_assistant import answer EVAL_SET = [ { "question": "SDK 默认超时是多少？", "expected_keywords": ["5 秒"], }, { "question": "认证返回 401 应该怎么排查？", "expected_keywords": ["环境变量", "token", "时钟"], }, ] def hit_keywords(response: str, keywords: list) -> bool: lower = response.lower() return all(k.lower() in lower for k in keywords) for item in EVAL_SET: resp = answer(item["question"]) status = "PASS" if hit_keywords(resp, item["expected_keywords"]) else "FAIL" print(f"{status}: {item['question']}") if status == "FAIL": print(resp)

这套评测集虽然简单，但它解决了布道工作里最要命的问题：文档改版之后，旧答案是否仍然正确，过去只能靠人一遍遍抽查，现在可以在每次文档变更后自动回归。

4.3 学习环境跑通与生产环境交付之间的差距

很多人把 2.2 的 RAG 示例部署上线后才发现，真正的成本不在模型调用，而在数据质量、评估回归和系统稳定性。学习环境里，文档只有几十个切块，怎么检索都能命中。生产环境里，文档可能有几万个切块，切分策略、检索 Top-K、重排、关键词兜底都会影响回答质量。

生产环境的额外要求至少要覆盖几个方面：第一，密钥和模型配置外置，不能写死在代码仓库。第二，每次回答要记录日志，包括用户问题、检索到的文档、模型答案和用户是否追问。第三，对文档和模型版本做回归，避免版本升级导致已回答正确的问题重新出错。第四，为模型输出增加引用来源，让开发者能回到原文核对。这些要求对布道师来说并不陌生，它们本质上就是过去“好文档”的工程化版本。

5. 传统布道师与 AI Engineer 的能力差在哪

5.1 工作产物和衡量指标对比

传统布道师的工作产物是文章、演讲、活动、标准文档；AI Engineer 的工作产物是系统、数据、评测、自动化流程。两者的反馈周期差别很大：文章发布后要等几周才能看到访问和 Issue，RAG 系统的回答质量当天就能从日志和评测集里看到。可扩展性也不同：文章的影响依赖推送和推荐，而一个问答系统可以长期、稳定、低边际成本地服务用户。

5.2 技能栈对比

写作能力不再是布道师的独占优势。AI Engineer 同样需要写作，但写作对象变了：要面向模型写提示词，面向数据写标注规范，面向开发者写可验证的文档。代码能力的要求也在提高，过去会写示例即可，现在要会做 CI、写好测试、处理异常和日志。

5.3 未来团队里两者不是二选一，而是分工变化

不是所有布道师都要马上变成纯 AI Engineer。现实团队里仍然需要人维护社区关系、处理重点客户问题、审校模型输出。变化的是权重：一个只会写文章的布道师，产出会被 AI 内容工厂快速摊薄；一个能构建 AI 问答系统、自动化示例验证和评测集的布道师，本质上就是 AI Engineer 在开发者关系领域的变体。团队在招人时，预算也会更愿意投向那些既能理解开发者场景，又能亲手搭系统的人。

从组织角度看，未来技术团队里更适合出现一个名为 Developer Experience AI Engineer 或 DevRel Engineer 的混合岗位。它负责的是一套开发者支持系统：文档仓库的机器可读性、RAG 问答的准确性、示例代码的自动回归、社区反馈到产品需求的自动化流转。这样的岗位既要有布道师对开发者场景的理解，又要有 AI Engineer 对系统质量的掌控。

对个人来说，不必等待公司创造这个头衔。手里有一个能回答真实问题的系统，比任何头衔都有说服力。你可以先用自己的技术博客做实验对象，把文档转成问答机器人，给它接上代码验证和评测集，然后把结果作为内部转岗或跳槽的材料。

6. 现在转型，四个动作要按顺序落地

6.1 把“会写”升级成“会写又会验证”

转型的第一个动作不是学 Prompt，而是保证你写出去的东西能运行、能回归。把个人博客或团队文档里的 Python 示例接入 CI，是成本最低的起点。具体做法是：建一个脚本，自动提取 Markdown 里的代码块，在沙盒环境运行，失败就让提交失败。这个动作看起来只是质量保障，它真正训练的是你把内容当成软件交付物的思维。

6.2 亲手完成一条 RAG 链路

第二个动作是亲手搭一条 RAG 链路，不要只看教程。选一份你熟悉的 SDK 文档，切成 20 到 50 个文本块，做向量化，在本地搭检索，然后回答 20 个你自己常被问到的问题。留意的细节包括：文本切块大小、是否保留标题层级、Top-K 取多少、检索不到时如何给出兜底回答、模型是否忠实引用了原文。只有亲手踩一遍这些问题，才算真正进入 AI 工程领域。

6.3 用数据反馈替代印象反馈

第三个动作是建立反馈数据。给问答系统加日志，记录哪些问题被频繁问、哪些问题答错、哪些文档块被大量引用。每周整理一份清单：没答上的问题归为三类，文档缺失、文档歧义、系统检索错误。这份清单就是布道师推动产品改进的最有力材料，它比感觉更有说服力，也比人工收集更完整。

6.4 建立可公开访问的作品集

第四个动作是做出作品集，而不是简历。建议三个仓库：一个是文档问答助手，展示你理解 RAG；一个是代码示例校验工具，展示你理解工程化；一个是不大于 100 条的开发者问题评测集，展示你理解开发者的真实痛点。每个仓库都要有可运行环境、清晰的 README 和评测结果。作品集的价值在于，换工作或内部转岗时，对方可以直接运行你的系统，而不是听你描述能力。

7. 转型过程中最容易踩的四个认知坑

7.1 把 Prompt 提升当成 AI 工程

提示词只是 AI 工程里很小的一部分。一个回答准确率稳定的系统，难点在数据切分、检索质量、评测回归和成本控制。只学 Prompt 很容易做出短期效果，但无法稳定支撑变更频繁的开发者工具场景。

7.2 让模型直接生成并发布事实性内容

大模型生成的内容如果不经过代码验证和事实核对，发布后会被检索系统继续放大。要区分生成和发布，生成可以由模型完成，发布必须经过验证。涉及 API 参数、版本号、执行结果的内容，必须用真实命令或真实运行结果兜底。

7.3 只搭系统不做回归

文档仓库一旦更新，RAG 回答就可能变。没有回归，一次改版可能让大量原本正确的问题答错。评测集要定期运行，文档变更时要自动触发，模型升级时要人工抽检。

7.4 把软技能当作无用资产丢掉

放弃软技能是最可惜的选择。这里真正需要的不是放弃软技能，而是改变软技能的使用方式。沟通能力用于定义业务问题，写作能力用于写评测集和标注规范，社区理解力用于设计开发者旅程。它们的输出形式变了，底层能力没有变。

这几个坑的共同特点是：用做内容的习惯做系统。内容讲究及时和表达，系统讲究稳定和可回归。可以每两周自检一次：你的评测集是不是还在增长？文档代码块有没有在 CI 里跑过？一次文档改版后，有没有出现原来通过、后来失败的用例？如果三项都是否，说明转型还停留在讲故事阶段。

8. 转型检查清单：把经验变成可运行系统

下面这份清单直接来自前面章节提到的工程闭环。它的目标不是让你一次完成，而是按顺序推进：先让数据可用，再让系统可跑，最后让质量可控。可以把每一项拆成两到三周内的任务。

8.1 环境与数据准备

• [ ] 本地环境有 Git、Python 3.11 或更高版本，以及 Docker。
• [ ] 已申请并配置好 LLM API 密钥，或部署了本地模型服务。
• [ ] 整理了最近三个月开发者高频问题，数量不少于 100 条。
• [ ] 把高频问题按主题分类，并标注答案对应的官方文档。

8.2 最小系统交付

• [ ] 完成一份文档的切分和向量化，向量库可用。
• [ ] 实现 RAG 问答接口，能返回带引用的答案。
• [ ] 编写不小于 20 条的评测集，跑出基线准确率。
• [ ] 给文档代码块接入 CI 验证，失败时阻止合并。
• [ ] 记录问答日志，至少包含问题、答案、关联文档和时间戳。

8.3 持续运营要求

• [ ] 每周检查未答上的问题，补文档或修正检索。
• [ ] 文档变动时自动触发评测回归。
• [ ] 模型版本升级后先跑评测集再上线。
• [ ] 整理一份错误回答案例集，作为下一步改进依据。

使用这份清单时要注意节奏。环境与数据准备尽量在两周内完成，不要追求完美，先收集够真实问题就能开始。最小系统交付阶段允许失败，重点是建立从文档切块到评估的完整链路。持续运营不是上线后才开始的，而是从第一条日志就开始积累。迭代频率可以这样安排：每天看错误回答日志，每周更新一次评测集，每月做一次评估回归并记录趋势。把布道师的经验转成系统之后，你会发现原先那些无法量化的付出，终于有了可以被团队理解和复用的落点。

回到开发者布道师是否消亡这个问题。更准确的说法是，布道师作为“人工翻译层”的形态正在被淘汰，但布道师掌握的领域知识、社区理解和踩坑经验，恰好是构建 AI Engineer 技术栈最需要的原料。如果你还在从事布道或技术内容相关工作，最值得马上做的事不是争论头衔，而是把经验变成可检索的数据、可运行的代码、可评估的评测集。当你能用一个系统服务一千个人的问题，并同时对答案质量负责时，你实际上已经完成了一次职业版本的 RAG 重构：原来的个人经验是基础模型，新构建的知识库、评测集和自动化验证，才是真正可扩展的上下文引擎。