Nstproxy 现已升级为 Nstdata。了解此次变化。
周一至周五 09:00 - 18:00（UTC+08:00） 公司地址
19H MAXGRAND PLAZA NO.3 TAI YAU STREET SAN PO KONG, KOWLOON HONG KONG ©2026 NST LABS TECH LTD. 保留所有权利。
Ivy Lin Community & Content Lead
从您的文档网站建立公司知识库 TL;DR
一个公司的文档助手是从一个选择的、版本化的文档语料库构建的，而不是从公司域名下每个 URL 的盲目复制。
爬取公共文档为 Markdown，保留产品/版本/语言元数据，然后进行分块、嵌入、检索，并要求源引用。
将私有文档作为一个单独的安全边界对待：爬虫不是身份提供者或权限过滤系统。
从一个产品和一个文档版本开始，使用实际支持问题进行验证，只有在访问和引用规则有效后才扩展。
介绍：为什么从文档网站构建知识库？
Nstdata Crawl 是此工作流程中的收集层；其 产品概览 描述了下游数据管道的页面和站点检索。
SaaS 文档网站通常会回答客户、支持和开发者的相同问题：如何进行身份验证，安装哪个 SDK 版本，参数的作用是什么，或者如何排查错误。一个基于检索的助手可以使这些页面更易于用自然语言查询，前提是索引保留了每个答案来自哪个产品和版本。
目标是一个有证据支持的搜索层，而不是自动真相引擎。如果摄取和评估较弱，系统可能会检索到过时的页面或误读参数表。Nstdata Crawl 可以提供页面内容作为 Markdown，并支持有限的站点发现；您的应用程序仍然负责任务选择、权限、索引、更新政策和答案行为。官方的 Crawl 文档 描述了获取层和输出格式。
你将构建的内容
公共文档页面
↓ 爬取和验证
Markdown + 来源元数据
↓ 规范化和分块
嵌入 + 向量记录
↓ 检索相关段落
助手回答，带源 URL 和版本标签
用户可能会问：“哪个头部验证当前 API？”助理应该从当前 API 版本中检索页面，引用相关证据，并显示其 URL。如果语料库同时包含旧版本和当前版本，而且问题未能明确指出使用哪个版本，助理应该询问或说明使用了哪个版本。
第一步：审核文档网站
从站点的信息架构开始，而不是抓取器。查看其网站地图、导航、版本选择器、地区路径、规范链接和身份验证边界。制作一个带有决策和所有者的URL表：
页面组 优先级 示例元数据 接入规则 入门指南 高 产品、语言、版本 包括当前版本 API 参考 高
更新日志档案 视情况而定 发布时间、状态 与当前文档分开
仅限登录的内部文档 单独项目 ACL 和所有者 不通过公共索引公开
识别高价值的文档页面 一个小型试点通常应涵盖入门、API 参考、身份验证、SDK 指南、故障排除和常见问题。这些类别回答具体的支持问题，并及早揭示解析问题。除非助手也旨在回答产品定位问题，否则请排除营销页面。
处理多个版本和语言 不要将 /v1/ 和 /v2/ 内容合并为一个无差别的集合。存储 product、version、language、status（当前/已弃用）和 canonical_url。根据用户选择的产品和版本应用检索过滤器。保持本地化页面的独立，因为翻译差异可能会影响参数和示例。
第二步：将公共文档抓取到 Markdown 使用站点级抓取从文档根目录开始，设置页面和深度限制。仅包括文档路径，排除登录/搜索路由和不相关的资产，并在索引之前检查发现的 URL 列表。首先使用一个具有代表性的静态页面、一个重代码的API页面和一个使用客户端渲染的页面进行小测试。
文档化的 Python SDK 支持一个 CrawlRequestDto，包括 url、formats、maxDepth、maxPages、includeUrls、excludeUrls、ignoreQuery 和 onlyMainContent 等字段：
import os
from nstdata_ai_crawl import CrawlRequestDto , Format , NstDataClient
with NstDataClient ( os . environ [ "NSTDATA_API_TOKEN" ] ) as client :
task = client . submit_crawl_task ( CrawlRequestDto (
url = "https://docs.example.com/" ,
formats = [ Format . MARKDOWN ] ,
maxDepth = 3 ,
maxPages = 250 ,
includeUrls = [ "*docs.example.com/*" ] ,
excludeUrls = [ "*docs.example.com/search*" , "*docs.example.com/login*" ] ,
ignoreQuery = True ,
onlyMainContent = True ,
timeout = 60_000 ,
) )
crawl_id = task . id
print ( crawl_id )
这是提交步骤；不要将返回的任务ID误认为已完成页面。轮询任务状态，浏览结果，并通过文档存储端点获取任何引用的Markdown工件。在运行报告中保留失败的URL。有关实用的爬虫到向量存储实现，请参见网站的Pinecone工作流指南 。
第3步：清理和组织内容 仅在它们明显是模板时，才删除重复的导航或cookie横幅。保留标题、代码语言标签、参数表、注意事项、链接和版本通知。前后示例应说明清理规则存在的原因：
Before: [Docs Home] [API] [SDK] | Authentication | Use the x-api-key header... | Related: SDKs
After: ## Authentication
Send the API token in the `x-api-key` request header...
“之前”行只是举例，而非爬取结果。对于每个真实页面，将提取的主体及其元数据存储在结构化记录中：
{
"source_url" : "https://docs.example.com/v2/authentication" ,
"canonical_url" : "https://docs.example.com/v2/authentication" ,
"title" : "Authentication" ,
"section_path" : "API Reference / Authentication" ,
"product" : "Example API" ,
"version" : "v2" ,
"language" : "en" ,
"crawled_at" : "2026-10-20T00:00:00Z" ,
"content_hash" : "sha256:..."
}
在运行时填充crawled_at；上面的日期是模式示例。使用标准化Markdown的稳定哈希来区分真实内容更改与重复爬取。
第4步：分块并嵌入技术文档 首先按标题分块。当API方法、端点、参数表、响应模式和相关代码示例描述一个操作时，将它们放在一起。如果一个部分超出了嵌入输入限制，在段落或代码示例边界处拆分，并将标题路径复制到每个块的元数据中。
为集合生成使用一个嵌入模型，并记录其名称。将source_url、title、version、language、section_path和crawled_at与每个记录一起存储。向量本身并不能替代文本或其引用元数据。有关嵌入请求合约，请参见OpenAI嵌入指南
第5步：使用版本过滤器存储和检索 此示例使用Chroma进行本地试点；其Python客户端和集合参考 记录插入文档
import chromadb
client = chromadb . PersistentClient ( path = "./docs-index" )
collection = client . get_or_create_collection ( "company_docs" )
collection . upsert (
ids = [ "auth-v2-001" ] ,
documents = [ "Send the API token in the x-api-key header." ] ,
embeddings = [ embedding ] , # 由您选择的嵌入模型生成
metadatas = [ {
"source_url" : "https://docs.example.com/v2/authentication" ,
"title" : "Authentication" ,
"product" : "Example API" ,
"version" : "v2" ,
"language" : "en" ,
"section_path" : "API Reference / Authentication" ,
} ] ,
)
在查询时，仅检索允许的产品/版本，并将源链接传递到答案提示中。测试直接API问题、特定版本问题和无法回答的问题。当检索到的证据不足时，助手应拒绝猜测。
第6步：构建文档问答助手 应用流是：对请求进行分类，应用用户允许的过滤器，检索段落，构建带有URL和版本的上下文，请求模型获取有根据的答案，然后验证返回的引用。响应应显示简洁的答案、指向源部分的链接和版本标签。记录检索的ID和提示版本，以便追踪不正确的答案。
在测试集中使用API验证问题、SDK安装问题和错误代码问题。对于每个测试，审核员应确认引用的页面包含所需的声明。如果指向旧版本，仅有匹配的URL是不够的。
处理缺失、冲突和过时文档 如果没有页面覆盖某个问题，请说明索引文档未确认答案。如果版本不一致，请检索用户选择的版本或询问澄清问题。如果某页面已被替代，请将其标记为弃用，并在默认的当前文档集合中筛选掉，同时在明确的历史查询中保留它。
第7步：保持文档索引更新 在计划内运行发现或从文档构建系统触发它，然后比较规范化的内容哈希。只有在新版本验证后，才重新嵌入更改的页面并删除过时的块 ID。将瞬态错误视为失败，而不是删除。在处理新的爬取时，保留最后已知良好的生成版本。
安全性和访问控制 公共和内部文档需要不同的访问控制。不要假设爬虫的 API 密钥会强制实施最终用户文档权限。对于私有页面，确认源所有者授权收集，保护凭证，分离索引或强制文档级 ACL 过滤器，并记录访问决策。默认情况下，绝不要将秘密或客户数据索引到共享集合中。在摄取机密材料之前，请咨询贵组织的安全团队。
NIST 的访问控制材料是设计政策边界的有用起点；请参见其 访问控制系统指导
成本、维护和常见问题 按爬取请求、代理使用（如适用）、嵌入令牌、向量存储、模型查询和工程维护进行预算。重新爬取的频率和文档的变化通常比首次导入更重要。在不测量每页生成多少块以及每页更改频率的情况下，切勿引用每页的总价；在预测之前请检查当前的 Crawl 定价 。
典型问题包括混合的 API 版本、重复的导航块、损坏的代码块、更新后仍然存在的过时记录、指向通用文档主页的引用，以及用户无法访问的内容。首先修复数据合同：稳定的 ID、规范 URL、版本元数据、允许列表和新鲜度作业。
启动检查清单
定义公共与私有源边界。
保持当前 URL 清单和明确的版本政策。
保留代码、表格、警告、URL 和版本元数据。
依据实际支持和开发者问题验证答案。
在返回检索的上下文之前强制执行用户权限。
监控更改检测、过时块、失败的 URL 和引用的正确性。
结论 来自文档网站的公司知识库在保留源上下文完整时获得成功。从一个小的公共语料库开始，明确建模产品和版本元数据，并要求助手引用它使用的页面。只有在检索过滤器和访问控制经过独立测试后，才添加私有或多租户内容。
常见问题解答 选择和爬取允许的页面，保留源元数据，清理并分块内容，嵌入它，存储在可搜索的索引中，并用引用验证答案。
可以，只要文档可以合法访问，并且其版本、语言和源 URL 保持附加在索引段落上。
将检索器连接到策划的文档索引，应用用户权限和版本过滤器，并指示模型根据检索到的段落回答并进行引用。
将 API 版本存储为元数据，保持版本独立，并过滤检索以满足用户问题相关的版本。
只有在明确的源授权和设计为对每个最终用户强制相同访问边界的情况下。
支持 JavaScript 渲染，成功率达 99.8%
将任意网站转换为 Markdown、HTML、JSON、链接、PDF 等格式，无需管理爬取基础设施。 开始免费爬取 →
