ARCHITECTURE · 2026-07-29
AZ OpsMate 架构总览从研究院原型到自研 .NET Agentic 平台
这份文档描述的系统，和微软研究院开源的 PIKE-RAG 已经没有一行共用代码。保留下来的是论文里的思想——专业知识与推理链增强；重写的是全部工程实现：679 次提交、1349 个 C# 文件、36 个模块化组件，Python 原型彻底退场。
57
Agent 与 Skill 定义 · YAML 驱动
01 — 项目历史
五个月，三次范式转换
项目起点是研究院开源代码的一次 Docker 化尝试，终点是一套自研的双后端 Agentic 平台。中间经历了三次不可逆的技术路线切换，每一次都推翻了上一阶段的核心假设。
2026-03
Python 原型期
以微软研究院 PIKE-RAG 开源实现为底座，完成 Docker 化部署与 Azure OpenAI Embedding 接入，搭建 RAGAS 评测框架。9 次提交。
2026-04
.NET 重写启动
确立 pike-agent 模块化单体架构，知识库、检索、网关三条主线并行开工。单月 159 次提交，全项目节奏最密集的阶段之一。
2026-05
平台能力成型 · GKB 上线
通用知识库交付生产。检索、画像、评测、沙箱能力齐备，205 次提交，全项目峰值。
2026-06
MAF 接入 · Agent 化改造
引入 Microsoft Agent Framework，Agent / Skill / Tool 三层抽象落地，MVR 业务开始按章节拆解。169 次提交。
2026-07
业务纵深 · 数据仓与个人工作区
MVR 工具技能化、个人工作区独立 schema、模板驱动的数据仓运行时。137 次提交，重心从平台转向业务。
565 commits
OpsMate 应用层、MVR 业务建模、数据仓管线、Agent 与 Skill 定义。端到端负责业务功能落地。
440 commits
Agent 运行时、知识库检索、AI 网关、画像与评测。提供平台侧通用能力。
98 commits
Nomad / Helm / Compose 三套部署编排，镜像构建与环境参数化。
02 — 与研究院原版的关系
思想保留，实现归零
这是理解本项目最关键的一点：PIKE-RAG 在这里是一个方法论名称，不是一份依赖包。研究院的 Python 实现已完全退场，当前代码库里与之相关的只剩下两个无关紧要的工具脚本。
研究院原版 · 已替代
- Python 实现，面向论文基准测试与实验复现
- 以脚本与配置文件驱动，单机批处理为主
- 知识库构建与检索耦合在同一套 pipeline
- 无多租户、无权限、无审计
- 无生产级可观测性与部署编排
当前自研 · .NET 实现
- C# / .NET 模块化单体，36 个 Pike.* 模块
- Abstractions 与实现分离，跨模块强制走显式契约
- 入库、检索、Agent 编排三层彻底解耦
- 完整身份体系、知识库作用域隔离、引用溯源
- Nomad / Helm / Compose 三套生产部署方案
关于命名的澄清
仓库名与模块前缀仍沿用 PIKE-RAG / Pike.*，但这指向的是论文提出的方法论——专业知识抽取、知识原子化、知识感知的任务分解。具体到工程实现，本项目是完全独立的重写。阅读代码时不应假设任何与开源版本的对应关系。
03 — 重写的真实脉络
没有一份文档写过「为什么」
先说清楚这一点
仓库里不存在任何 .NET 选型的决策记录——没有 ADR，没有选型对比，没有「Python 哪里不行」的清单。docs/archive/csharp_rewrite_analysis.md（1882 行）是唯一一份重写文档，但它开篇自述「仅分析，不修改代码」，性质是执行计划而非决策记录。下方时间线与动机分析，凡标注「推断」者均为依据代码证据的推测，不可当作当事人陈述引用。
时间线 · 全部有 commit 佐证
03-19
仓库建立
Chen 提交 initial commit，Yanzhi Li 补技术分析文档。起点是研究院 Python 开源实现。
03-26
Yong Ma 接手
Docker 化部署 + Azure OpenAI Embedding。此后 Python 期 96 个提交中 84 个出自他一人。
04-20
.NET 骨架落地
d61f4f23 基于 CleanArchitecture 模板建 pikerag-net，同一提交附上重写分析文档。
04-21
范围一天内扩张
文档从「不迁移对话、向量操作、文档处理」改为「不迁移对话、文档处理执行」，Workflow / Artifact / Admin 全部纳入。
05-29
Python 全部删除
306c82fc 移除 api / shared / pikerag 三个 Python 项目。计划中「保留」的部分最终一并迁走。
起手并不是「全面重写」
04-20 那份文档写得很克制，策略是增量共存而非推倒重来。
原计划 · 双服务共存
- C# 提供 /api/v3，Python 保留 /api/v1 /api/v2
- Nginx 按 URL 前缀分流，共享同一个 PostgreSQL
- C# 只做基础数据 CRUD 与管理面
- 明确列章说明「不迁移对话、向量操作、文档处理」
实际结果 · 39 天后
- Python 三个项目全部删除，无共存期遗留
- 对话、向量、文档处理全部由 .NET 承接
- 模块数扩张到 36 个 Pike.*
- 范围扩张的原因未见任何文档说明
动机分析
推断 · 非接手他人代码
重写的是自己刚写的
Python 期 84/96 个提交出自 Yong Ma 本人。这不是「嫌前人代码差」的重构，而是同一人对自己两个月前成果的推翻。动机因此更可能来自形态判断而非代码质量。
推断 · 技术栈一致性
全程贴合微软生态
.NET 10 · EF Core · Aspire · OpenTelemetry · Azure OpenAI · Azure Document Intelligence，最终接入 Microsoft Agent Framework。客户 AstraZeneca 是微软大客户且部署在 Azure——但没有任何文档写明「因客户要求」。
推断 · 从计划内容反推
目标是工程化，不是性能
重写文档大篇幅讲 Clean Architecture、CQRS、统一响应信封、审计字段自动填充、JWT + API Key 双路径认证——全是企业级治理能力，通篇未提性能。研究院原型本就没有多租户、权限与审计。
04 — 系统架构
双后端 + 双前端
系统按「平台底座」与「业务应用」两层切分，各自有独立的后端服务与前端应用。平台提供通用 Agentic 能力，应用承载 AstraZeneca 特定业务逻辑。
平台后端 · pike-agent
核心能力
Agent 运行时 · 知识库 · 检索 · AI 网关 · 沙箱 · 评测 · 身份
入口
Web（API）· JobRunner（异步任务）· Migrator（迁移）
应用后端 · app
定位
AstraZeneca OpsMate 业务实现
项目
OpsMate.API · OpsMate.Init
核心能力
个人工作区 · MVR 业务域 · 数据仓实例 · Agent/Skill 定义种子
数据
独立 opsmate schema，与平台库隔离
前端 · web
技术栈
React + TypeScript + Vite，211 个 TS/TSX 文件
应用
AstrazenecaOpsMate（业务端）· admin（管理端）
构建
按应用独立 vite config 与 tsconfig，产物分离
平台模块分组
Agentic · 11 模块
Agent 运行与治理
Runtime 负责执行，Skills / Tools / Definitions 管理能力资产，Workspace 提供文件工作区，Sandbox 隔离代码执行，Profiling 与 SkillMining 支撑能力沉淀。
Knowledge · 10 模块
知识入库与检索
Pipelines 承担入库编排，Documents 管理文档与向量检索，Files / Kbfs 处理存储，Profiling 做文档画像，Wiki 支撑结构化知识。
Platform · 其余
基础设施能力
AiGateway 统一模型接入与池化，Identity 负责身份鉴权，DataWarehouse 提供模板驱动的数据仓，Evaluation 支撑质量评测。
05 — 自研 PIKE-RAG
论文思想如何落到这套代码里
论文的核心主张是：仅靠检索不足以支撑工业场景，必须显式地抽取专业知识、并构建推理链。本项目把这个主张拆成了三条可工程化的实现路径。
论文 · 知识库分层
入库即结构化
文档不是切块了事。入库管线依次完成资产落湖、内容解析、画像抽取、切块、向量化，产出的是带元数据与结构信息的知识单元，而非裸文本片段。
论文 · 知识原子化
画像与属性重写
Knowledge.Profiling 对文档做分类与业务元数据抽取，RewriteDocumentAttributes 将非结构化内容提炼为可检索属性，对应论文中从数据块挖掘多维知识的主张。
论文 · 推理链构建
Agent 迭代取证
复杂问题不做单轮检索。LoopAgent 驱动多轮迭代，Agent 按需委派 worker 分头取证，逐步累积证据后一次性作答，对应论文的任务分解与推理链累积。
检索实现
检索层建立在 Milvus 之上，默认走混合通道。
向量库
Milvus · 按知识库维度隔离 collection，支持文档级过滤
检索通道
hybrid（默认）· dense 与 sparse 双路召回后经 RRF 融合；亦支持单独走 sparse 或 dense
Embedding
默认 bge-m3，按知识库可配置；经 AI 网关池化调度
重排
独立 reranker 池，与 embedding 分离配置
分数策略
hybrid 模式下不施加分数阈值——RRF 分数与相似度不可比，强行过滤会误伤
排序策略
支持 document_order，按文档与块顺序还原原文脉络，供需要连续上下文的场景使用
入库管线
这是全系统唯一使用工作流引擎（Elsa DAG）的地方——因为入库是确定性的多阶段批处理，天然适合 DAG 编排。
STEP 01
Raw Asset 落湖
原始文件入对象存储，登记资产元数据
STEP 02
Curate 解析
经 Document Intelligence 转为结构化 Markdown
STEP 03
Warehouse 入仓
切块、画像抽取、属性重写
STEP 04
Vectorize 向量化
批量嵌入并写入 Milvus
STEP 05
Search Tokens
构建稀疏检索所需词元索引
06 — 模型与外部依赖
已全面转向 Foundry
早期方案依赖内网自建 GPU 推理服务，当前生产已改为云端 Foundry 托管模型。内网仅保留一项：文档识别。
推理模型 · 云端 Foundry
对话模型
gpt-5.4 · 经 Foundry 部署，Agent 全链路统一走此模型
接入方式
经 Pike.AiGateway 统一代理，模型池配置存于数据库，支持运行期切换
鉴权
网关 master key 机制，业务侧不直接持有模型凭据
文档识别 · 内网容器
服务
Azure Document Intelligence · 以容器形态部署在内网
用途
PDF 与图片转结构化 Markdown，是入库管线的前置依赖
部署考量
临床文档不出内网，故识别环节本地化；容器需 healthy 后其余服务才启动
已废弃的路径
代码库中仍保留 src/vllm 目录与本地 GPU 模型部署脚本，属历史遗留。当前生产不再使用内网自建推理服务，相关文档与 compose 模板中的 GPU 资源规划仅对早期客户 VM 方案有效。阅读部署材料时须注意区分。
07 — 从这里继续
四份延伸文档
理论基础
用通用方法拆解 arXiv:2501.11551 的核心理念：四类问题分级、知识原子化、知识感知的任务分解，以及它们为何适配临床文档场景。
技术核心
双路召回与 RRF 融合、rerank 阈值的真实生效范围、引用如何做到可溯源，以及跨知识库检索的已知取舍。
工程实现
Microsoft Agent Framework 用了什么、没用什么。为何放弃 Workflow 而全用 Agent，MVR 十六章如何一章一 Agent 加工具组合。
运维交付
Compose / Nomad / Helm 三套编排的适用场景、服务拓扑、启动顺序与外部依赖清单。