问题

传统的关键字搜索（如 docmd 的内置搜索）依赖于精确的文本匹配。如果用户搜索“身份验证”，基本的关键字引擎可能会因为页面标题为“集成 OAuth2”且该词出现频率不够而无法找到该页面。语义搜索使用向量嵌入来理解查询的 含义，解决了这个问题，但需要特定的文档结构才能有效。

为什么重要

现代开发者期望直观、基于意图的搜索体验。如果您的文档由于微小的术语差异而无法显示相关内容，用户将很快放弃您的网站并寻求其他帮助。为语义搜索进行设计可以确保您的文档在用户使用不同术语时仍具有可发现性。

方法

组织您的文档，使其易于被检索增强生成 (RAG) 流水线消费。这涉及创建“语义密集型”内容，其中概念被清晰定义，并且代词被显式实体替换，以便在分块和向量化过程中保留上下文。

实施

1. 丰富的 Frontmatter 元数据

使用 Frontmatter 提供在正文中可能不会自然使用的显式关键字和描述。这为搜索引擎提供了额外的内容“挂钩”。

---
title: "集成 OAuth2"
description: "了解如何实现安全的身份验证和单点登录 (SSO)。"
keywords: ["login", "authentication", "sso", "security", "identity"]
---

2. “语义密度”策略

RAG 系统将文档切分为小块（向量）。每个章节的第一段应该包含与该主题相关的、密度最高的名词和动词。这确保了该章节的主要“含义”被捕获在初始向量中。

• ✅ 正确：“本指南解释了如何实施 OAuth2 单点登录 (SSO)，为您的文档网站提供安全的 身份验证。”
• ❌ 糟糕：“在本节中，我们将讨论它是如何工作的，以及您如何轻松地设置它。”

3. 避免代词歧义

在分块数据库中，如果定义“它”的前一个段落被切分到了不同的块中，那么像“它适用于任何提供商”这样的句子就是无用的。请务必显式表达。

• ❌ 歧义：“它具有高度的可扩展性。”
• ✅ 显式：“docmd 搜索引擎 旨在具有高度的可扩展性。”

权衡

为语义密度而写作有时会比传统的叙述性写作感觉稍微正式或具有重复性。然而，由此带来的可发现性的提高以及 AI 生成回答的准确性，使得这成为现代企业级文档的重要实践。