Strata Agent 指南：AI 助手如何为用户安装 Qwen3.8-Flash-Next 本地推理引擎并参与代码工作

本文以仓库根目录的 AGENTS.md 为主线，完整展开 Strata 为 AI 编码助手编写的两份操作规范：如何按 docs/AI_SETUP.md 为用户安装、启动并验证 Strata（Qwen3.8-Flash-Next 在单张 NVIDIA/AMD 显卡加系统内存上运行，提供 OpenAI/Anthropic 兼容 API），以及如何按仓库约定参与代码与文档工作。读完你应能独立完成"检查 PC → 选模型 → 非交互安装 → 启动验证 → 接入应用 → 排错"的全流程，并知道哪些文档和测试是开发协作的依据。

一、项目结构：Agent 首先要掌握的三块组件

AGENTS.md 开篇用三句话定义了 Strata 的组成，这也是后续所有操作的落点：

• 推理引擎：C++/CUDA/HIP 实现的推理内核，源码在 src/ 与 include/（如 src/core/ 的会话与设备管理、src/kernels/ 的解码/预填充内核、src/prefill/ 的矩阵与 MoE 融合路径）；
• Python 服务层：serve/ 目录，含 OpenAI 与 Anthropic 兼容 API 及一个 Web 应用（serve/server.py、serve/web/index.html），默认监听 http://127.0.0.1:8080；
• 一键安装器：setup.py，由 Windows 的 START-HERE.bat 或 Linux 的 setup.sh 拉起。

setup.py 文件头的 docstring 把首次运行的流程写得很清楚，共 7 步且每步完成后再次运行会跳过：1) 检查 PC（NVIDIA/AMD 显卡与驱动、内存、CPU、磁盘）；2) 询问问题（模型家族、尺寸、上下文、是否读图）；3) 把 Python 依赖装进 .venv；4) 获取引擎——RTX 20/30/40/50 有现成构建，不匹配时装编译工具并现场编译，AMD 在 Windows 下载现成 HIP 引擎、在 Linux 本地编译；5) 从 Hugging Face 下载模型（可断点续传）及可选的视觉编码器；6) 为 Strata 准备模型并拉取约 5 GB 的 MTP 草稿层；7) 写出 run-<model>.bat / run-<model>.sh 并启动模型。Python 依赖由 requirements.txt 按版本钉死（如 numpy 按 Python 3.10/3.11/3.12+ 分档），保证任意日期检出都装同一套包。

二、为用户安装 Strata：基本守则

AGENTS.md 的核心指令是：安装用户机器时按 docs/AI_SETUP.md 的步骤依次执行，全程用平实语言向（可能非技术的）用户说明你在做什么。该文档第 0 节给出四条基本守则：

1. 绝不无密钥暴露服务。保持默认 --host 127.0.0.1；只有用户明确要求跨设备访问时，才用 --host 0.0.0.0 且同时加上 --api-key <一个长的随机秘密>，并把密钥交给用户。任何情况下不要在无密钥的服务前架隧道或端口转发。
2. 改动范围限于安装器本身。setup 只会在必要时为用户账号安装 Python，其余都落在 Strata 目录及其旁边的 Strata-data 目录里；安装显卡驱动前必须先征询用户。
3. 先确认下载量。模型约 70 GB（Unsloth 4-bit 最大 111 GB），计量网络下尤其要先征得同意。
4. 安装是长任务且可续传。慢网络下一小时起步；应后台运行或给足超时、轮询输出，不要因为它安静了一会儿就杀掉它。重跑同一条命令会从断点继续。

三、检查这台 PC

最快的方式是 setup 自带的检查——打印显卡、驱动、内存、CPU、磁盘空闲空间以及"这台 PC 能否运行 Strata"，不安装任何依赖（除运行所需的 Python 与 .venv）：

Windows:  START-HERE.bat --check
Linux:    ./setup.sh --check

手动检查命令对照表（来自 docs/AI_SETUP.md 第 1 节）：

项目	Windows (PowerShell)	Linux
系统	[Environment]::OSVersion	cat /etc/os-release
NVIDIA 显卡、显存、驱动	nvidia-smi --query-gpu=index,name,memory.total,driver_version --format=csv	同左
AMD 显卡	Get-CimInstance Win32_VideoController | Select-Object Name, AdapterRAM（AdapterRAM 上限 4 GB，以型号名为准）	lspci | grep -i -E 'vga|display'；显存 cat /sys/class/drm/card*/device/mem_info_vram_total（字节）；已装 ROCm 时可用 rocm-smi
内存	(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB	free -g
磁盘空闲	Get-PSDrive -PSProvider FileSystem	df -h .

硬件门槛（详见 docs/INSTALL.md）：

• GPU：NVIDIA RTX 20/30/40/50 系列，或 AMD Radeon RX 7900 XT/XTX、RX 7800 XT/7700 XT、RX 9060 XT、RX 9070/9070 XT、Radeon AI PRO R9700、RX 6800/6900 系列；显存 12 GB 以上（8 GB 的 NVIDIA 卡能跑但很慢）。GTX 10 系及更早、核显不支持。
• 驱动：NVIDIA 580 或更新；AMD 在 Linux 用内核 amdgpu 驱动，Windows 用最新 Adrenalin 驱动。驱动缺失或过旧时让用户自行更新并重启，未经要求不要替用户装驱动。
• 内存 32 GB 以上（见下文选型）；磁盘约 80 GB 空闲，最好 NVMe SSD；CPU x86-64 且支持 AVX2。
• 系统：Windows 10/11 或 Linux（Ubuntu 22.04/24.04 全自动）。

不满足时，指出缺哪一项并停止，而不是硬装。

四、获取 Strata 并按内存选模型

仓库获取：git clone 官方仓库，或下载 main 分支源码 zip 解压。要选磁盘空闲足够的盘：模型文件放在 Strata 目录旁边的 Strata-data 文件夹（也可用 --data-dir <path> 指到别的盘）。

按内存选模型（docs/AI_SETUP.md 第 3 节的完整表格；先问用户是否主要写代码——是则任意内存下 Coder 都是好选择）：

内存	--family / --model	备注
32 GB	--family coder（尺寸 IQ1_M）	面向代码；配 24 GB 显卡时 Q2_0 与 IQ2_XS 也可跑（setup 会自动选低内存模式）
48 GB	--family qwen --model IQ2_XS	或 Q2_0（最快）
64 GB	--family qwen --model IQ2_XS（推荐）	IQ3_XXS / IQ3_S 更慢、略好
96 GB+	--family qwen --model IQ3_S	--family unsloth --model UD-Q4_K_XL 为实验性：仅 NVIDIA、需 NVMe SSD，64 GB 机器上约 7-8.5 tokens/s

--family swift（Swift 1.5，思考更短的微调；尺寸 Q2_0、IQ2_XS、IQ3_XXS）是 qwen 的替代。加 --yes 且不给 --model 时，setup 会按内存自行选推荐尺寸。模型清单与说明见 docs/MODELS.md。

五、无问答运行 setup

在 Strata 目录内（Windows 用 cmd，或从 PowerShell 执行 cmd /c START-HERE.bat ...）：

Windows:  START-HERE.bat --yes --family qwen --model IQ2_XS --no-start
Linux:    ./setup.sh --yes --family qwen --model IQ2_XS --no-start

全部参数（START-HERE.bat --help 可查）：

参数	含义
--yes	所有问题取推荐答案（不提问）
--family qwen|swift|coder|unsloth	模型版本
--model Q2_0|IQ2_XS|IQ3_XXS|IQ3_S|IQ1_M|UD-Q4_K_XL	尺寸（Coder 为 IQ1_M，Unsloth 为 UD-Q4_K_XL）
--context N	上下文 token 数；按显存取默认：14 GB 以下 32768，20 GB 以下 65536，否则 131072
--vision yes|no|gpu|cpu	是否读图；--yes 下默认关闭。AMD 卡用 cpu
--gpu N / --gpus 0,1 / --gpus all	单卡或多卡分摊模型（默认取显存最大的卡）
--backend cuda|hip	NVIDIA 或 AMD 引擎；只有一种卡的 PC 上自动选择
--data-dir PATH	70-120 GB 模型文件的存放位置
--port N	服务端口（默认 8080）
--host H --api-key K	监听超出本机；必须与密钥一起给
--no-start	只安装、不启动服务
--setup	另装一个模型，或修改已装模型的配置
--check	只做 PC 检查

对 Agent 特别推荐的 --no-start：服务前台运行直到窗口关闭，会阻塞你的 shell；按第 6 步单独启动。setup.py 头部还列了若干进阶参数：--rope-scaling none|linear|yarn（超过训练上限 262144 时 setup 会自动加 yarn 缩放，显式 none 会被拒绝）、--models-dir / --gguf-dir（复用已有 GGUF 分片）、--build（现场编译代替现成引擎）、--kv-streaming on|off|auto 等。

各平台的注意事项（原文档"Notes"一节，完整继承）：

• Linux：setup 会用 sudo apt（或 dnf/pacman）在缺 Python 时安装带 venv 的 Python，AMD 机器可能还需要 build-essential 和 git。你无法替用户输入密码：需要 sudo 的步骤时，请用户自己执行（如 sudo apt install python3-venv build-essential git）后重跑 setup。
• Linux 上的 AMD：除非系统已有 ROCm 7，否则 setup 把 ROCm 装进 .venv（约 10 GB，无需 sudo），并为该卡编译引擎（一次 10-20 分钟）。ROCm 来源与 hipBLASLt 调优表的细节见 docs/AMD_HIP.md。
• Windows 上的 AMD（0.1.34 起）：setup 下载现成 AMD 引擎（约 550 MB，含 ROCm），不编译、只需 AMD 驱动；模型下载前会跑 engine\strata-device.exe --list-devices 自检，列不出卡就是驱动问题。当前 Windows AMD 支持每模型一卡、暂不支持图像。
• NVIDIA 无现成引擎适配的卡：setup 会提议装编译工具并编译（20-40 分钟），--yes 即接受。

六、下载期间如何与用户沟通

docs/AI_SETUP.md 第 5 节要求 Agent 在下载期间主动说明四件事：

1. 将从 Hugging Face 下载约 70 GB；100 Mbit/s 带宽约 1.5-2 小时；可随时中断，重跑会续传。
2. 下载后还要为该 PC 准备模型（几分钟），Linux 上的 AMD 会编译引擎。
3. 模型开始加载时 PC 可能卡顿甚至 1-3 分钟无响应（首次最久）：Strata 会把 35-55 GB 读进内存并锁定一部分供显卡使用，属正常现象，不要关窗口。
4. 一切都在本地：模型不出这台 PC。

七、启动服务并验证

setup 会打印它写出的启动脚本（start script: run-<model>.bat）。脚本名是家族标签加尺寸（小写）：run-iq2_xs、run-swift-iq2_xs、run-coder-iq1_m、run-unsloth-ud-q4_k_xl。

Windows (PowerShell):  Start-Process -FilePath ".\run-iq2_xs.bat"            （开独立窗口）
Linux:                 nohup ./run-iq2_xs.sh > strata-server.out 2>&1 &

也可以不带参数直接跑 START-HERE.bat / ./setup.sh，它会启动已安装的模型（装过多个时会问选哪个，加 --yes 取第一个）。服务就绪后会打开用户浏览器指向 http://127.0.0.1:8080。关闭窗口（或结束进程）即停止模型。

HTTP 服务在模型加载完成后应答（首次几分钟，之后 30-90 秒）。轮询验证：

curl http://127.0.0.1:8080/health

返回形如 {"status": "ok", "model": ..., "max_context": ..., "images": ..., "api_key": ..., "loaded": true, ...}。随后：

curl http://127.0.0.1:8080/v1/models
curl http://127.0.0.1:8080/v1/chat/completions -H "Content-Type: application/json" -d "{\"model\": \"strata\", \"messages\": [{\"role\": \"user\", \"content\": \"Say hello in five words.\"}], \"max_tokens\": 64, \"reasoning_effort\": \"none\"}"

配置了密钥时加 -H "Authorization: Bearer <key>"。服务窗口打印 ready: http://127.0.0.1:8080/v1 即就绪；引擎日志在 Strata 目录下的 strata-<model>.log。

八、把用户的应用接进来

docs/AI_SETUP.md 第 8 节给出的接入清单：

• 浏览器：http://127.0.0.1:8080，含 Chat、实时 Monitor 与 About（设置与地址）。
• 任意 OpenAI 兼容应用/Agent：base URL http://127.0.0.1:8080/v1，API key 任意（或已配置的密钥），模型名任意。
• Anthropic 兼容应用：http://127.0.0.1:8080/v1/messages。
• Claude Code：ANTHROPIC_BASE_URL=http://127.0.0.1:8080，ANTHROPIC_MODEL 设为它认识的任意 Claude 模型名（Strata 忽略该名字），ANTHROPIC_AUTH_TOKEN 任意（或已配置密钥）。
• 思考级别：请求体里 "reasoning_effort": "none" | "low" | "medium" | "high"（默认 high）。

注意 Strata 一次只处理一个请求。API 细节见 docs/DETAILS.md 的 "Using it" 一节。

九、出错了怎么办：症状处置表

docs/AI_SETUP.md 第 9 节维护了一张对照表，Agent 应优先按它处置：

症状	处置
the NVIDIA driver is too old	用户更新驱动（NVIDIA App 或 nvidia.com/drivers）并重启，重跑 setup
下载或安装中断	重跑同一条 setup 命令；它会续上
port 8080 is already in use	Strata 已在运行（查 /health），或用 --port 8081
很慢、磁盘繁忙或 "the engine stopped unexpectedly"	空闲内存不足：关程序，或用 --setup --model Q2_0（或 IQ2_XS）装更小的尺寸
ExpertCache: cudaMalloc(...) failed: out of memory 但显存有剩余（Windows）	分页文件关闭或太小：改为"系统管理"并重启
prompt ... exceeds the context	用 --setup --context <更大值> 重跑 setup
Linux 找不到 AMD GPU	内核 amdgpu 驱动未列出 GPU；检查卡与驱动，核显不支持
Python 或编译工具装不上	按报错提示装上对应组件（提示里有链接），再重跑

更多排查见 docs/TROUBLESHOOTING.md 与 docs/DETAILS.md 的完整故障表。仍失败时收集 strata-<model>.log 与 setup 输出，引导用户到仓库 issues 反馈。

十、替代方案：用 MCP 服务器管理安装

AGENTS.md 指出 shell 命令之外还有第二条路：Strata 自带 MCP 服务器（docs/MCP_SERVER.md），把同样的步骤暴露成工具调用。实现是单文件 tools/strata_mcp.py，只用标准库（因此 .venv 建立之前也能跑），stdio 传输，Python 3.10+。工具集（参数均可选）：

工具	作用
strata_status	是否有模型在跑（模型、引擎版本、上下文、忙闲、VRAM/RAM 占用）、已装内容、本机硬件、setup 对本机模型与上下文的推荐
strata_models	setup 提供的全部家族/尺寸、下载体积、所需内存、是否适配本机、是否已装、上下文推荐
strata_install	无问答地后台执行 setup；不带 confirm: true 只返回计划；再调一次看进度；cancel: true 取消
strata_start	后台启动已装模型并轮询 /health 直到应答；wait_seconds（默认 50）内未就绪返回 "loading"
strata_stop	先经服务器 API 卸载模型，再结束自己启动的进程
strata_logs	取 server / engine / setup 三类日志的末尾
strata_benchmark	发一个短固定请求（贪心、关闭思考），报告 prompt/输出 tokens/s
strata_connect_info	OpenAI/Anthropic base URL、模型 id、是否需要密钥，以及 Claude Code、OpenAI SDK、curl、Cursor、Continue、Open WebUI 的现成配置

从文档描述看，strata_install 复用 setup.py 自身的 MODELS、FAMILIES、CONTEXTS 表与内存检查来补全缺省值，并走与 START-HERE.bat / setup.sh 相同的 7 步流程（.venv → setup.py --yes --no-start ... 后台运行，输出进 .strata-mcp/setup.log）。其安全约束值得注意：所有参数对照固定 schema 校验、命令以参数列表传递不经过 shell、唯一的路径参数 data_dir 必须落在允许的目录集合内（拒绝 ..、相对路径与 UNC 路径）、进程按"PID + 启动时间"双匹配才允许结束、且安装前必须显式 confirm: true。测试 tools/test_strata_mcp.py 用假的 setup 与服务器跑通全流程，不下载、不用 GPU。

十一、参与代码工作：文档索引与无 GPU 测试

AGENTS.md 的 "Working on the code" 一节是贡献者的文档地图，指向四份权威资料：

• 引擎原理、每个实测数字、API 与全部设置：docs/DETAILS.md 与 论文；
• AMD（HIP）构建与验证：docs/AMD_HIP.md（含 gfx1100/gfx1101/gfx1200/gfx1201/gfx1030 的 ROCm 来源、编译与 hipBLASLt 调优表）；多 GPU 层切分：docs/MULTI_GPU.md。

setup 自身的测试不需要 GPU、不需要下载，命令形如 python tools/test_setup_<name>.py。tools/ 下这一族文件包括 test_setup_amd.py、test_setup_choices.py、test_setup_draft_vocab.py、test_setup_lowram.py、test_setup_prompts.py、test_setup_risk.py、test_setup_rope.py、test_setup_unsloth.py、test_setup_update.py、test_setup_pins.py、test_setup_golden.py 等。从源码结构看，这些测试通过 mock 与临时目录验证 setup 的决策逻辑：例如 test_setup_amd.py 用伪造的 KFD 拓扑（/sys/class/kfd + /sys/class/drm）验证 gfx 架构名、HIP 编号、支持的卡与 TheRock 索引选择；test_setup_choices.py 验证现成引擎缺某卡代码时回退 CPU 视觉编码器、GGUF 分片数等分支。文件 docstring 也给出了等价的 python -m unittest tools.test_setup_amd 调用方式。实测数据快照则沉淀在 bench/results/ 各日期目录下，与文档中"每个数字都注明测于何处"的风格一致。

最后一条是文档风格规范：用平实的词；写实测数字时必须写清测在哪台机器上；没有测量就不要下断言。这条约束贯穿 docs/ 全目录——例如 docs/DETAILS.md 的速度表都标注了具体显卡、CPU、内存、引擎版本与基准目录，可作为撰写新文档时的模板。

十二、收尾自检清单

综合 AGENTS.md 与 docs/AI_SETUP.md，交付前可对照：

1. 服务只监听 127.0.0.1，除非用户明确要求且已带 --api-key；
2. /health 返回 loaded: true，/v1/chat/completions 能出完整回复；
3. 用户的应用（浏览器/OpenAI 客户端/Anthropic 客户端/Claude Code）已按第八节接入；
4. 失败时按第九节对照表处置，并保留 strata-<model>.log 与 setup 输出；
5. 若走 MCP 路径，确认工具返回的 JSON 中计划与进度符合预期，且未触碰本机之外的网络。

按此流程，AI 助手可以完全按仓库文档执行、无需临场发挥，就能把 Strata 装到一台普通 PC 上并让用户的现有应用直接连上本地模型。