DWS 知识问答最佳实践
面向 AI Agent 的 DWS数据仓库服务离线知识库。内置华为云官方文档 ，支持 agent 离线检索并带官方 URL 出处回答。
纯离线运行：检索阶段零联网、零第三方依赖（Python 3 stdlib 即可）。检索由脚本完成，LLM 只读命中的 chunk 正文。
Skill 地址：hwc-dws-knowledge-qa（随 hwc-dws-cli 分发，源码位于 dws-cli 仓库 agent_skills 目录）
快速开始
- 目录结构。
dws-knowledge-qa/ ├── SKILL.md # Agent 协议（触发词/检索流程/行为约束）——挂载给 agent 的核心 ├── README.md # 说明 ├── references/ │ ├── search-guide.md # 检索策略手册（LLM 检索时参考） │ └── index/ │ ├── catalog.json # 文档域元数据 │ ├── sections.json # 每域页面清单（标题/官方URL/chunk区间） │ └── pack/*.jsonl # 全量 DWS 文档切分的 chunk └── scripts/ ├── common.py # 共享工具 ├── search.py # 分层检索入口（LLM 唯一需要的工具） ├── fetch_llms.py # 从华为云 llms.txt 下载官方文档（数据更新用） └── build_pack.py # 构建索引（数据更新用） - 挂载到你的 Agent。
挂载后，agent 会通过 SKILL.md 的触发词识别 DWS 问题场景，然后调用 search.py 完成分层检索（--list-docs → --list-sections → --query → --read）。
- 验证挂载成功。
python scripts/search.py --list-docs # 应列出所有文档域 python scripts/search.py --query "集群扩容" --doc mgtg-dws --topk 5 python scripts/search.py --read mgtg-dws:0001
search.py 使用说明
search.py命令说明如表1所示。
| 命令 | 说明 |
|---|---|
| --list-docs | 列出全部文档域（slug/页数/chunk数） |
| --list-sections <slug> | 某域的页面清单（标题/官方URL/chunk区间） |
| --query "<关键词>" [--doc <slug>] [--section <子串>] [--topk N] [--json] | 分层检索，只输出元数据（不含正文） |
| --read <doc:chunk-id>... | 输出 chunk 全文（唯一放大文本的入口） |
示例：
python scripts/search.py --query "GDS" --doc migration-dws --topk 5 python scripts/search.py --query "列存表" --doc devg-dws --section "选择DWS表存储模型" python scripts/search.py --read sqlreference-dws:0001 tg-dws:0007
出处格式：答案引用 [页面标题](官方URL)，如 [DWS SSD云盘和SSD本地盘的区别](https://support.huaweicloud.com/dws_faq/dws_03_2141.md)。 联网可单击直达原文；不联网时 URL 作为稳定标识，仍可追溯页面标题。
数据更新
内置库已打包好，开箱即用。如需更新到华为云最新文档：
# 1. 下载最新官方文档（需联网，可访问 support.huaweicloud.com） python scripts/fetch_llms.py --url https://support.huaweicloud.com/dws/llms.txt # 2. 重建索引 python scripts/build_pack.py
增量更新（两种模式）：
# 模式A：只下载新增页面，已存在的跳过（不检查内容是否变化） python scripts/fetch_llms.py --skip-existing --url https://support.huaweicloud.com/dws/llms.txt # 模式B：已存在的也重新下载，内容有变化才覆盖（推荐用于日常更新） python scripts/fetch_llms.py --update-changed --url https://support.huaweicloud.com/dws/llms.txt # 两种模式执行后都要重建索引 python scripts/build_pack.py
--update-changed 会输出每页状态：[SAME] 内容未变保留 / [CHANGED] 已更新覆盖 / [OK] 新增。
自定义文档：把自己的 md 放进 sources/<域>/ 后重跑 build_pack.py 即可并入索引。
文档域一览
内置文档域如表2所示。
| slug（域前缀） | 内容 |
|---|---|
| sqlreference-dws / sqlreference-911-dws | SQL 语法参考（9.1.0 / 9.1.1） |
| devg-dws / devg-911-dws | 开发指南（9.1.0 / 9.1.1） |
| mgtg-dws | 用户指南（集群管理/控制台操作） |
| api-dws | API 参考 |
| dws_faq | 常见问题 |
| trouble-dws | 故障排除 |
| bestpractice-dws | 最佳实践 |
| migration-dws | 数据迁移与同步 |
| tg-dws | 工具指南（gsql/GDS/DSC/DataCheck） |
| errorcode-dws / errorcode-new-dws | 错误码（8.2.0 及以下 / 8.2.1 及以上） |
| productdesc-dws | 产品介绍 |
| price-dws | 计费说明 |
| bulletin-dws | 服务公告/版本说明 |
| qs-dws | 快速入门 |
| pwp-dws / pwp-910-dws / pwp-911-dws | 性能白皮书 |
| sdkreference-dws / clir-dws | SDK / CLI 参考 |
常见问题
- Q: 需要联网吗？
检索阶段不需要——索引和 chunk 全部离线内置。只有「数据更新」 需要联网拉取华为云文档。
- Q: 需要安装第三方库吗？
不需要。search.py / build_pack.py / fetch_llms.py 全部 使用 Python 3 标准库（urllib/argparse/json/re/pathlib）。
- Q: 支持哪些 Python 版本？
Python 3.8+ 均可（含 3.12）。
