你的 AI 助手回答 Vivado 问题时，是在"凭记忆编"，还是在"查文档答"？
AMD 官方给出的答案是后者——而且检索过程可以全程不出你的电脑。

一、Doc Search 是什么

amd-embedded-doc-search 是 AMD Embedded Agentic AI Suite 提供的一套本地文档检索栈（RAG）。它把 AMD Embedded 的全量官方文档——Vivado、Vitis、Power Design Manager、ChipScope、System Software、example designs、Wiki 页面、Answer Records——做成一个本地向量数据库，让 AI 助手能够基于真实文档、带引用地回答问题。

它的架构设计有一个非常清醒的特点："在哪检索"和"谁来写答案"彻底解耦。

• 检索层（嵌入模型 + 向量库 + MCP Server）永远在本机，无论如何；
• 回答层（LLM）由你选：可以用 GitHub Copilot 这样的云端前沿模型，也可以用本地 ROCm GPU 跑的开源大模型，实现端到端零出网。

官方文档里有个贯穿全文的比喻，把 RAG 讲得很透彻：

• 嵌入模型 = 图书馆员的索引卡系统。它不懂你的问题，但能极快地判断"哪些文档跟这个主题相关"；
• LLM = 真正读卡片并用人话解释给你听的人。它的知识冻结在训练时点，自己不会查资料。

两者职责不可互换——这正是 RAG 要把两者接起来的原因。也特别提醒一个常见混淆：嵌入模型 ≠ 回答用的 LLM。前者只有 300M–600M 参数、输出是几百个数字、永远本地；后者几十 GB、输出是人类可读的答案、由你挑选。

二、为什么要本地部署

1. 离线环境可用。很多芯片、航空航天、国防、商业敏感客户的开发机根本不通外网。本地部署后，文档检索全程在单机完成，不需要把任何查询发到外部服务。

2. 数据不出本机。你的提问往往包含项目细节——"我的 Kintex UltraScale 设计在 report_utilization 里 BRAM 用了 87% 该怎么办"。这类问题发送到云端，等于把项目信息送了出去。本地检索消除了这个泄露面。

3. 检索质量稳定可控。云端搜索受网络、服务变更影响；本地向量库是一次性导入的确定快照（如 Docs_07162026），版本固定、结果可复现。

4. 快。实测直接调用 MCP 检索接口，单次往返只要20–31 ms，且与查询内容无关、非常恒定。这个速度对 Agent 场景至关重要——AI 助手一轮对话里可能要调好几次检索。

5. 硬件门槛低。嵌入模型只有几百 M 参数，CPU 就能跑；快照是预向量化的，目标机连向量化算力都不需要。

三、在线还是离线？先选对路线

AMD 官方现在提供两种文档检索路线：

1. 官方托管的在线知识库（Vivado Doc Search MCP，端点https://vivado.amd.com/mcp/doc-search，接入方法见上一篇文章《为Ai Agent接入 Xilinx 在线知识库》，

2. 离线知识库（amd-embedded-doc-search 本地RAG）。

两者检索能力同源，差别在部署形态与数据边界：

在线知识库更适合谁：网络通畅的个人开发者、学习和评估阶段的用户、追新特性的早期采用者，以及已经在用云端 LLM、不想维护任何基础设施的人，不希望占用额外的本地磁盘和运行内存，不愿意签NDA用户。

离线知识库更适合谁：开发机不通外网或有保密要求的单位；查询内容敏感、不允许出网的企业内网；需要固定文档版本做审计与问题复现的团队；以及打算搭配本地 LLM（ROCm）实现端到端零出网的进阶玩家。

一句话：求快求新选在线，求稳求私密选离线。两者也可以并存——联网时查最新，断网时用本地快照。

四、技术栈：四个容器各司其职

注意三个常驻容器都不是 LLM——这个栈只负责检索，写答案的模型另配。这也是它能如此轻量的原因。另外这些镜像随 tarball 分发、从本地 tar 加载，不需要访问公网镜像仓库；表中版本号以你手中包内的实际镜像为准。

工具名叫 vivado_doc_search 是历史遗留（为客户端兼容保留），实际搜的是整个 AMD Embedded 语料，不只是 Vivado。

五、如何部署

📌 版本说明：本文基于 AMD 2026-07-31 发布的 Early Access 文档（CLI 0.4.2 版）。正式发布前，CLI flags、镜像版本号等细节可能调整，请以你手中 tarball 内的 README 为准。

5.1 为什么用 Docker：整套服务，一条命令

Docker 是集装箱式的应用打包与运行平台：把"应用 + 它依赖的一切（库、运行时、配置）"打包成一个镜像，镜像在任何装了 Docker 的机器上都能跑出一模一样的环境。它解决三个经典麻烦：

1. 环境一致性——根治"在我机器上能跑"病。应用依赖什么库、什么版本，全部封死在镜像里，与宿主机装没装、装的是什么版本无关；
2. 隔离——容器之间、容器与宿主机系统互相隔离，跑数据库、跑编译服务互不污染；不要了整体删除，不留残渣；
3. 一次打包，到处运行——开发机、服务器、客户的离线机跑的是同一份镜像，行为可复现。相比虚拟机，容器共享宿主机内核、秒级启动、内存开销小得多。

放到本方案里，Docker 的作用一目了然：第四节那张表里的四个容器（Weaviate、llama.cpp、MCP Server、一次性 importer），如果手动安装，你要分别处理三套安装流程、版本兼容、端口分配和重启策略；而实际上它们的镜像全部随 tarball 分发，部署时从本地 tar 加载——离线机器也能一条命令拉起整套服务。你日常用的 start / stop / ps / logs / stats / purge，本质上都是 docker compose 操作的封装。

5.2 安装 Docker 并确认环境

按操作系统选择安装方式：

• Windows / macOS：安装 Docker Desktop，启动后等托盘图标显示就绪；
• Linux（联网）：安装 Docker Engine + Compose 插件，按发行版用包管理器安装；
• Linux（离线/气隙）：推荐静态 tarball 方案——从 download.docker.com/linux/static/stable/ 下载 docker-.tgz、从 GitHub docker/compose releases 下载 compose 二进制。静态包自包含，能绕开离线装 .deb/.rpm 时依赖无法解析的经典死结。

装完后先验证：

$ docker ps# 能列出（空）容器列表，说明 daemon 正常$ docker compose version        # 能打印版本号，说明 Compose 插件就绪

Linux 上如果 docker ps 报 docker.sock permission denied，说明当前用户不在 docker 组——这是管理操作，找系统管理员加组或按安全策略处理。

然后跑一次内置体检，让工具替你逐项确认：

    $ amd-embedded-doc-search doctor

它会检查 Docker CLI、daemon、Compose 插件三项，并对任何缺失项打印出确切的修复命令——只读检查，不安装任何东西。doctor 通过之前不要往下走。

其余前置条件：约8 GB 空闲磁盘；一个回答用的模型（云端 Copilot 或本地 LLM）和一个支持 MCP 的 AI 客户端——它们只负责"写答案"，本篇的栈只负责检索。

5.3 解包分发包

文档不是随压缩包分发的——tarball 里只有 CLI、模型和镜像。以 Docs_07162026-embeddinggemma-300m-0.4.2-amd64.tar.gz 为例，解包（建议先建独立目录再解，因为包是扁平结构、无外层文件夹）：

$ mkdir docsearch && cd docsearch      $ tar xzf ../Docs_07162026-embeddinggemma-300m-0.4.2-amd64.tar.gz  

Windows 下也可以直接用资源管理器解压，或系统自带的 tar -xzf（Windows 10 及以上内置 bsdtar）。解出后内容如下：

amd-embedded-doc-search          CLI 二进制（Linux）amd-embedded-doc-search.exe      CLI 二进制（Windows）README.md / NOTICEmodels/embeddinggemma-300M-Q8_0.gguf    嵌入模型（~330 MB）images/  ├── weaviate.tar               向量库镜像  ├── llama.cpp.tar              嵌入服务镜像  ├── doc-search-mcp-server.tar  MCP server 镜像  └── snapshot.tar               预向量化语料快照（~2.4 GB）

之后运行 CLI 用对应平台的二进制即可：Linux 下先 chmod +x amd-embedded-doc-search；Windows 下直接用 amd-embedded-doc-search.exe（下文命令统一以 Linux 写法为例）。

5.4 配置与起栈

完成 5.2 的体检后，剩下的流程是"配置 → 启动 → 确认"：

② 交互式配置configure。运行：

$ amd-embedded-doc-search configure --start 

--start 表示写完配置后直接起栈；不加则只生成配置，稍后手动 start。配置向导是交互式 TUI 表单（需要在真终端里运行，脚本自动化时要加 pty 包装），依次让你确认三件事：

1. Collection——要导入的文档快照；
2. 嵌入模型——二选一（见 5.5）；
3. MCP 端口——默认取 ≥8080 的第一个空闲端口。

机器上有 AMD GPU 的话，可以改用 amd-embedded-doc-search configure --gpu --start，用 ROCm 加速嵌入模型，首次导入会更快。

生成的部署文件全部落在 ~/.config/amd-embedded-doc-search/：docker-compose.yaml（栈定义）、class-config.json（向量化配置）、.env（端口、API key、模型设置）。Weaviate 的 API key 首次自动生成，之后复用，不用你管。

两个注意点：如果你的 home 目录在 NFS 上（stat -f -c '%T' "$HOME" 显示 nfs），建议先 export XDG_CONFIG_HOME=/local/path 再运行任何命令，把配置和数据整体移到本地盘，避开 NFS root_squash 导致的权限问题；要换嵌入模型或文档快照时，重新运行 configure 即可，但换模型前必须先purge（原因见第七节避坑清单）。

③ 启动与观察。加了 --start 的话栈已经在起；单独启动用：

$ amd-embedded-doc-search start

start 包装的是 docker compose up，默认前台运行——按 d 转入后台（栈继续跑），Ctrl+C 则停止。首次启动会自动加载 images/ 里的四个镜像 tar，然后按顺序拉起 Weaviate、llama.cpp、MCP Server 三个常驻容器，并启动一次性的 snapshot importer。用 ps 观察状态：

$ amd-embedded-doc-search ps

④ 确认状态。三个常驻容器最终都应显示 running/healthy；首次导入期间 importer 在跑、mcp 容器可能短暂显示 Created，这正常——详见 5.6。

5.5 嵌入模型怎么选

官方明确说明：两者的检索质量对比尚未发布，所以目前只能按许可证或体积选型——有 Apache 2.0 顾虑的选 qwen3，在意体积的选 gemma。

注：目前实测 embeddinggemma-300m版本解压失败，只有qwen3版本可用。需要获取向量库镜像文件，请联系自己区域的Xilinx FAE签署NDA后获取。

5.6 首次导入与验证

ps 显示全部 healthy 之前不要连客户端。首次导入需要把约 71 万个文档块（~714k chunks）灌进 Weaviate 并构建向量索引，CPU 上约10 分钟——这是预期的一次性工作，不是卡死。期间的表现和解法：

• mcp 容器显示 Created：一次性导入还在跑。想盯进度可以看 importer 日志，它会自己跑完退出：

  $ docker logs -f amd-embedded-doc-search-weaviate-docs-import-1

• 刚导入完报 Connection reset by peer：预期且无害——importer 填完 Weaviate 后 MCP 容器会自重启，等它的状态起来 15–30 秒再重试。

• 随时看整体状态：amd-embedded-doc-search ps（容器）、logs --follow（日志）、stats（CPU/内存/IO）。

全部 healthy 之后，按第六节把端点接进客户端，验证是否打通。

5.7 内存占用：向量进内存，文本落盘

读者最常问的两个问题：这套栈吃多少内存？会不会把整个向量库都加载进内存？

先说结论：文本块（对象）主要落盘存储，不会全量进内存；但向量索引的主体常驻内存——这是 HNSW 近似最近邻算法的工作方式，图结构必须在内存里才能高速遍历。准确地说：向量在内存里，文本不全在。

官方只给了 ~8 GB 磁盘的指标，未公布内存数字。以下是实测数据（qwen3-embedding-0.6B / 1024 维部署，Windows 11 + Docker Desktop，语料已导入、栈已稳定运行两天）：

两个值得注意的点： 

1. llama.cpp 比直觉占得多——2.8 GiB 里只有 ~1.2 GB 是模型本体（f16），其余是 server 常驻的计算缓冲；本文初稿曾按"模型大小 + 少量开销"估成 0.5–1 GB，实测翻了倍。预留内存时请以实测为准。
2. compose 实际带了内存限额：Weaviate 限 14 GiB、MCP 限 1 GiB，llama.cpp 不限（吃满主机）。Weaviate 的限额与向量图规模同阶（71 万 chunks × 1024 维 × 4 字节 ≈ 2.9 GB，加图边与开销），语料翻倍前先确认这个限额的余量。

按架构估算的参考值（无实测条件时）：Weaviate 约 3–4 GB（gemma 768 维）/ 4–5 GB（qwen3 1024 维），MCP 几十 MB，整机建议预留 8 GB 空闲内存——与上方实测吻合。

想要实测值，首次导入完成后跑一次：

$ amd-embedded-doc-search stats# 每容器实时 CPU/内存/IO      # 或$ docker stats

显示的数字就是你这台机器上的真实预算。

六、怎么用：接入 AI 助手

服务跑起来后，把 MCP 端点配进你的 AI 客户端：

{        ”amd-embedded-doc-search”: {         ”type”: ”http”,    ”url”: ”http://127.0.0.1:8080/mcp/doc-search”  }}

JSON 的外层结构因客户端而异：有的客户端直接把上面这个对象写进 MCP 配置，有的则要求再包一层 "servers": { ... }。配好后连不上时，先核对你所用客户端要求的结构。另外示例中的 8080 是默认端口——如果你的 configure 分配了其它端口（见 ~/.config/amd-embedded-doc-search/.env 里的 DOCSEARCH_MCP_PORT），请相应替换。

⚠️ 写 127.0.0.1，不要写 localhost。 在部分环境里 localhost 会解析到 IPv6 的 ::1，而 Docker 只把端口发布在 IPv4 上，客户端会报 HTTP 000 连不上。这是排障表里的第一条。

验证方法很简单：在 Agent 模式里问一句"Search UG904 for incremental compile."——看到 vivado_doc_search 被调用、并返回带来源的文档块，就通了。

至此，"部署 → 接入 → 验证"闭环完成。

七、运维要点与避坑清单

三个最容易踩的坑：

1. 换嵌入模型必须purge，不能stop。stop 故意保留 Weaviate 数据卷。如果你从 embeddinggemma（768 维）换成 qwen3（1024 维）却只 stop，importer 看到 collection 已存在会跳过导入，旧向量被原样复用——之后所有搜索报 vector lengths don't match。正确姿势：purge --yes → configure --start。

2. 别用代码专用模型当回答模型。代码模型倾向于"凭训练记忆直接答"而不调搜索工具，产出听起来合理但可能错误的答案。这条云端、本地模型都适用。

3. 答案要以检索结果为准。官方给 Agent 的行为规则值得全文照抄：每个事实断言都要有检索结果支撑并附来源 URL；源里没写的命令、参数、约束一律不许自己补；答案末尾必须有Sources列表。

八、小结

Doc Search 的价值一句话概括：让 AI 助手从"背诵型选手"变成"查资料型选手"，且查资料这件事完全发生在你的机器上。部署成本就是"装 Docker + 跑三条命令 + 等 10 分钟导入"，换来的是可复现、可离线、可审计的官方文档问答能力(如果您签了NDA，拿到镜像文件和pdf user guide，可以直接把User guide丢给您的Agent，让AI帮您完成部署，如果遇到问题，可以将这篇公众号链接分享给AI作为参考)。

对于大部分工程师来说，Xilinx不是唯一厂商，我们在开发过程中还会用到其它厂家的芯片，比如DRAM，MCU或各种接口PHY芯片等，这些器件手册在Xilinx提供的文档库里面并找不到，下一篇，我们聊聊官方库之外——如何自己动手做一个完全自定义的本地文档库，作为Xilinx文档库的补充。