AI 工程师的技术博客——怎么写才有价值

我写这个公众号快 4 年了，前两年几乎是零反馈，偶尔有人点赞，大多数文章阅读量在几十到一两百之间。那时候我也怀疑过：到底有没有必要坚持写？

转折发生在 2023 年初，我写了一篇踩坑记录——在生产环境里因为 Milvus 的一个版本升级，导致向量检索结果莫名其妙地变差，排查了三天，最后发现是索引参数的默认值在新版本里变了。那篇文章发出去之后，一周阅读量破了万，还收到了十几个私信，都是遇到类似问题的工程师。

那是第一次，我真正理解了技术文章的传播逻辑。

这篇文章不讲"为什么要写技术文章"，那个问题我在 1337 篇里讲过了。这篇讲的是更具体的事：什么样的内容真正有传播价值，写什么类型的文章，以及怎么让文章被搜索到。

三种技术文章，传播逻辑完全不同

在开始之前，先把常见的技术文章类型分清楚，因为不同类型的文章，写作策略和目标读者完全不同。

类型一：教程类

"从零开始学 LangChain"、"10 分钟搭建你的第一个 RAG 系统"——这类文章。

特点：步骤清晰，手把手，适合新手入门。

问题：存量巨大，同质化严重。你写的"LangChain 入门教程"，和已有的几千篇教程竞争，凭什么被人找到？而且大模型的更新速度极快，教程类文章的时效性很短，写了三个月的教程可能六个月后就过时了。

不是不能写，但不应该是你的主要输出。

类型二：踩坑记录

"记一次 Milvus 索引参数变更导致的检索质量下降问题"——这类文章。

特点：具体场景，真实错误，有完整的排查过程，有最终解决方案。

传播逻辑：长尾搜索流量。搜索"Milvus 检索准确率下降"的人，数量不多，但他们几乎一定是真实遇到这个问题的人，他们会认真看你的文章，会收藏，会分享给同样遇到问题的同事，甚至会来私信你问更多细节。

踩坑记录的价值：每一篇都是一个精准的长尾入口，积累了足够多之后，搜索引擎会把你的博客认定为垂直领域的权威来源。

这是技术工程师最容易写、传播效率最高的文章类型。

类型三：观点文章

"我为什么认为 Agent 框架在 2025 年还不够成熟用于生产"——这类文章。

特点：有明确判断，有个人立场，不是中立的综述，可能引发争议。

传播逻辑：认同感或争议性讨论。读者读到一篇和自己判断一致的观点文章，会有强烈的共鸣感，会转发给同类；读到和自己判断相反的观点，会有想反驳的冲动，也会转发去"批评"或者"讨论"。无论哪种，都会带来传播。

观点文章的风险：如果你的判断是错的，而且文章流传很广，会影响你的技术信誉。所以写观点文章，要有充分的实践依据，不要为了"有观点"而强行输出结论。

适合有一定积累、有自己判断的时候写。

什么样的技术文章真正有传播价值

这不是一个主观问题，有几个可以验证的维度。

维度一：解决了一个真实存在但网上缺乏答案的问题

搜索一下你准备写的主题。如果搜出来前三页都是高质量的详细答案，那你再写一篇加入这个竞争，没有意义。

但如果你搜索"LangChain 中文文档的 chunk 策略"，发现结果要么是英文、要么是泛泛而谈，没有真正解决中文场景下语义切分的实际问题，那这就是一个值得写的选题。

判断标准：搜索这个问题，会有人找不到满意答案吗？

维度二：有具体的细节，不是泛泛的建议

"RAG 系统要注意数据质量"——这句话是对的，但对读者没有价值。

"我们在处理 PDF 格式的技术文档时，发现直接使用 PyPDF2 提取的文本，在表格和图表区域会产生大量乱码和无意义片段，这些片段进入向量库后严重影响召回质量。我们后来的解决方案是：对 PDF 先做版面分析，用 pdfplumber 提取表格数据并转为结构化文本，图表区域用 GPT-4V 做图片描述，再和正文文本合并处理。"——这有价值。

判断标准：读完之后，读者能立刻知道怎么做吗？

维度三：有你自己的判断，不只是"整理资料"

工程师写技术文章最常见的模式是"综述"——把几个工具的功能都列出来，然后说"各有优缺点，根据场景选择"。

这种文章毫无价值，因为你提供的信息和官方文档一样，还比官方文档不权威。

有价值的是："我用了这三个工具，在我们的场景里，A 工具在中文语料上的表现明显优于 B 和 C，原因我分析是 XXX。如果你的场景是 YYY，那可能 C 更合适，因为 ZZZ。"

判断标准：去掉你的个人判断之后，这篇文章还有独特价值吗？如果没有，说明判断部分是核心。

维度四：时效性和长效性的平衡

技术文章分两种：

• 时效性内容：某个新框架刚出来的第一批评测文章，某个大模型刚发布的能力分析。这类文章的流量集中在发布后一两周，之后快速衰减。
• 长效性内容：某类问题的通用解决思路，某个踩坑记录（如果问题没有被框架修复）。这类文章持续带来稳定的长尾流量，一年后还有人在搜。

建议的比例：70% 长效内容，30% 时效性内容。 时效性内容帮你获取短期曝光，长效内容建立持续的流量基础。

踩坑记录怎么写：一个完整的框架

踩坑记录我建议用这个结构，这是我自己总结的，测试下来效果比较好：

1. 一句话描述问题

用读者可能会搜索的语言描述问题，不用技术术语。比如：

• "LangChain 调用 OpenAI API，偶发性超时，但重试后成功"
• "Milvus 3.0 升级后，相同查询的召回结果变少了"

2. 环境信息

框架版本、语言版本、操作系统。这一步很多人省略，但对于遇到同样问题的人，环境匹配非常重要。

3. 问题复现步骤

最简化的复现代码。如果能提供一个最小化复现示例，文章价值会翻倍，因为读者可以直接在自己的环境验证。

# 复现示例：LangChain 超时问题
from langchain_openai import ChatOpenAI
from langchain.schema import HumanMessage

# 问题场景：高并发下偶发超时
import asyncio

async def test_concurrent_calls():
    llm = ChatOpenAI(model="gpt-4o-mini", timeout=30)
    
    tasks = [
        llm.ainvoke([HumanMessage(content=f"问题 {i}")])
        for i in range(20)  # 并发 20 个请求时开始出现超时
    ]
    
    results = await asyncio.gather(*tasks, return_exceptions=True)
    errors = [r for r in results if isinstance(r, Exception)]
    print(f"错误率: {len(errors)}/{len(results)}")

4. 排查过程

真实的排查思路，包括走过的弯路。这部分很多人想省略，但往往是最有价值的部分，因为读者在排查类似问题时会走同样的弯路，你的弯路记录帮他们节省时间。

5. 根本原因

找到的真实原因，尽量精确到代码层面或者配置层面。

6. 解决方案

完整的解决方案代码或配置。

7. 总结和预防

这类问题的通用预防原则，或者类似问题可能出现的其他场景。

观点文章怎么写：让判断有说服力

观点文章最大的错误是"标题党"——标题写得很刺激，内容却是空洞的结论堆砌。

有说服力的观点文章，结构应该是这样的：

1. 亮明立场

开头直接说清楚你的核心判断，不要绕圈子。

2. 交代你的判断依据

你是在什么场景下得出这个结论的？你有多少相关经验？这决定了你的判断有多大的参考价值。

3. 承认对立观点的合理性

如果你的观点有争议，先承认另一方的合理之处，然后说为什么你的判断更适用于某些场景。这比直接否定对立观点更有说服力。

4. 具体的案例支撑

不要只有逻辑推理，要有真实案例。"我在 A 项目里尝试了 XXX，结果是 YYY，因此我认为 ZZZ"——这比"根据 XXX 理论，YYY 应该是这样"更可信。

5. 给读者一个可操作的结论

观点文章的目的，是帮读者做决策，不是让他们佩服你聪明。最后的结论要落到具体的行动建议上。

从写到被搜到：SEO 的工程师版理解

我不想讲 SEO 理论，讲几个工程师视角下最实用的原则。

原则一：标题即搜索词

搜索引擎优化的第一步，就是想清楚你的目标读者会用什么词来搜索这个问题，然后把这些词放在标题里。

"我的 RAG 踩坑记录"——对 SEO 没有任何帮助。

"RAG 系统中文查询召回率低的根本原因和解决方案"——有帮助，因为有人会真的用这些词来搜。

这不是说要在标题里堆砌关键词，而是要用目标读者的语言来描述问题，而不是你自己的语言。

原则二：文章结构对 SEO 有影响

搜索引擎会解析页面结构。使用 H2/H3 标题、有逻辑的段落划分、清晰的代码块——这些不只是可读性的问题，也会影响搜索引擎如何理解和索引你的内容。

原则三：长文比短文更有 SEO 价值

同等质量下，覆盖一个话题更全面的长文，比浅尝辄止的短文更容易排到搜索结果前列。这是因为长文通常包含更多的相关关键词，也更可能被其他网站引用。

这也是我为什么建议每篇文章至少 3000 字——不是为了凑字数，而是真正把一个问题讲透，通常需要这个篇幅。

原则四：内链比你想象的重要

如果你写了很多文章，在新文章里引用和链接相关的旧文章，会形成一个相互增强的内容网络。搜索引擎会认为这些文章构成了对某个话题的系统性覆盖，整体权重会高于孤立的单篇文章。

原则五：平台选择影响搜索效果

在国内，微信公众号的内容在搜狗能被搜索到，但百度收录效果不稳定。掘金、CSDN 的文章在百度收录效果好。知乎的回答经常排到搜索前列。

如果你想最大化搜索流量，最好的策略是：在自己的博客（GitHub Pages 或者独立域名）发布原始内容，同时在掘金/CSDN 发布，在公众号发布，引用回你的博客。

量化指标：怎么判断你的文章有没有效果

很多人写了一段时间，不知道有没有效果，于是放弃了。这里给几个具体的量化指标参考。

阅读量

对于刚起步的技术博客，我认为合理的进步路径是：

• 第 1-20 篇：每篇 200-500 阅读是正常的
• 第 20-50 篇：开始出现几篇 1000+ 的文章
• 第 50 篇以后：应该有稳定的 3-5 篇爆款（5000+ 阅读）

如果你写了 30 篇，每篇还是在 100 以下，不是坚持的问题，是选题或者写法需要调整。

收藏和分享比

阅读量是表面数据，收藏比（收藏数/阅读数）更能反映文章的实际价值。

如果一篇文章有 2000 阅读，50 个收藏，说明 2.5% 的人觉得这篇值得留下来，这是个不错的比率。

如果有 5000 阅读，但 0 收藏，说明这篇文章可能是标题吸引人但内容没价值，引来了流量但没留住。

私信和评论的质量

如果一篇文章发出去，有人来私信说"在你的文章里找到了解决方案，谢谢"，或者问了你一个进阶问题，这是比阅读量更有价值的信号——说明你真的解决了别人的问题。

搜索来源占比

大多数内容平台都有"流量来源"统计。如果你的流量里有 20% 以上来自站内搜索或者外部搜索引擎，说明你的内容有 SEO 价值，会持续带来新读者；如果全是来自你自己发链接，说明文章没有独立传播能力。

写作节奏：可持续地输出

最后说一个很实际的问题：频率。

很多工程师会经历：刚开始热情高涨，一周两篇；三个月后，一个月一篇；六个月后，完全停了。

原因通常是：选题枯竭，或者写作负担太重。

解决选题枯竭的方法：建立一个选题库。每次在工作中遇到一个有趣的问题，或者读到一个让自己有反应的东西，立刻记录下来。不需要完整的想法，一个关键词或者一句话就够。等你坐下来写的时候，打开选题库，选一个开始写。

我自己的选题库现在有 200 多个条目，大部分永远不会被写，但它保证了我不会坐在空白文档面前不知道写什么。

解决写作负担太重的方法：降低你对每篇文章的完美度要求。一篇有真实内容的 2000 字文章，比一篇精雕细琢的 5000 字文章更容易发出去，而且对读者的价值未必更低。

先完成，再完善。

我现在写一篇文章，大概花 2-3 小时。刚开始写的时候，一篇文章要花一整天，因为想把每个细节都写完美。降低标准、提高频率，反而让内容的整体质量提高了——因为保持持续输出，会让你的思考更深入，写作更流畅。