MAS_Metax V1 — 离线多智能体深度研究框架

版本 1.1.0 | 运行环境 沐曦 GPU + vLLM | 模式离线容器化推理

概述

MAS_Metax V1 是一个专为沐曦 GPU 容器环境设计的离线多智能体研究系统。六个专业 LLM Agent 协同完成深度研究任务——从课题分解到多轮检索、证据分析、报告撰写和质量审核，最终产出完整的 Markdown 研究报告，并提供全链路审计追踪和可视化。

核心能力

能力	说明
Agent 独立选模	6 个 Agent 在运行时可各自选择不同的本地模型
多轮检索	迭代式查询生成 → 召回 → 相关性评分 → 查询精炼
知识库沉淀	高质量检索结果持久化到本地知识库，后续运行可复用
质量闭环	Reviewer 评分 → ReviewFeedback 回退修订 → 闭环通过
GPU 显存管理	加载新模型前自动卸载旧模型，防止显存溢出（V1.1）
全链路审计	每次 LLM 调用记录 Agent、用途、温度、Token、耗时
运行可视化	自动生成 SVG/HTML 仪表盘，展示工作流、时间线和 Agent 用量
离线运行	无需公网；可选 Web Search 在可用时启用

快速开始

# 冒烟测试（Mock 后端，无需 GPU）
python run.py --demo --print-report

# 列出可用模型
python run.py --list-models

# 真实运行，逐个指定 Agent 模型
python run.py \
  --topic "沐曦容器内基于 vLLM 的离线多智能体推理框架" \
  --backend vllm \
  --agent-model Orchestrator=Qwen3-4B \
  --agent-model Researcher=Qwen3-4B \
  --agent-model Analyst=Qwen3.5-9B \
  --agent-model Writer=Qwen3.5-27B-W8A8 \
  --agent-model Reviewer=Qwen3-30B-A3B-Thinking-2507 \
  --agent-model ReviewFeedback=Qwen3-30B-A3B-Thinking-2507 \
  --source examples/metax_local_notes.md

# 连接已有的 vLLM OpenAI 兼容服务
python run.py \
  --topic "国产 GPU 离线 LLM 推理框架评估" \
  --backend openai \
  --base-url http://127.0.0.1:8000/v1 \
  --model-name Qwen3-8B \
  --source examples/metax_local_notes.md

架构

用户课题 / Query
       │
       ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Orchestrator   │────▶│   Researcher     │────▶│    Analyst      │
│  任务理解与分解  │     │  多轮检索 +      │     │  证据分析与      │
│                 │     │  知识库沉淀      │     │  洞察提炼        │
└─────────────────┘     └────────┬─────────┘     └────────┬────────┘
                                 │                        │
                    ┌────────────┴────────┐               │
                    ▼                     ▼               │
            ┌──────────────┐    ┌─────────────────┐       │
            │  本地知识库   │    │   Web 搜索      │       │
            │  (词法检索)   │    │  (DDGS/Bing)    │       │
            └──────────────┘    └─────────────────┘       │
                                 │                        │
                                 ▼                        │
                        ┌─────────────────┐               │
                        │   相关性评分    │               │
                        │  (LLM + 词法    │               │
                        │   回退算法)     │               │
                        └────────┬────────┘               │
                                 │                        │
                    ┌────────────┴────────────┐           │
                    ▼                         ▼           │
            ┌──────────────┐         ┌──────────────┐     │
            │  精炼知识库   │         │   证据池      │◀────┘
            │  (持久化)     │────────▶│  source_hits  │
            └──────────────┘         └──────┬───────┘
                                            │
                                            ▼
                                   ┌─────────────────┐
                                   │     Writer      │
                                   │  Markdown 报告  │
                                   └────────┬────────┘
                                            │
                                            ▼
                                   ┌─────────────────┐     ┌──────────────────┐
                                   │    Reviewer     │────▶│ ReviewFeedback   │
                                   │   质量审核       │     │  修订计划 +      │
                                   │   JSON 输出     │     │  闭环验证        │
                                   └────────┬────────┘     └────────┬─────────┘
                                            │                       │
                                            │    ┌──────────────────┘
                                            ▼    ▼ (回退)
                                   ┌─────────────────┐
                                   │   最终报告       │
                                   │   + 可视化       │
                                   └─────────────────┘

架构要点：

每个 Agent 独立选择模型。模型分配记录在 model_assignments.json 中，并在仪表盘中可视化。
Researcher 同时查询本地词法知识库和可选的 Web 搜索引擎。Web 结果会记录 url、provider 和 retrieved_at。
检索执行多轮迭代：初始查询 → 召回 → LLM 相关性评分 → 查询精炼 → 再次召回。
每次检索周期结束后，精炼知识写入 data/knowledge/refined/ 并刷新语料索引。
Analyst 区分本地来源支持、Web 最新信息支持、模型推理和已识别的信息缺口。
Reviewer 检查 <think> 泄漏、无来源性能数字、虚构对比表和缺失的 URL 引用。
ReviewFeedback 将审核结果映射为回退计划：证据缺口触发 Researcher，分析不足触发 Analyst，表达/引用问题触发 Writer。
每次 LLM 调用均记录 Agent 身份、用途、模型、温度、max_tokens、输入输出字符数和耗时。
所有日志持久化到 log/ 目录，失败时自动生成结构化错误摘要。

Agent 详解

Agent	职责	温度	Max Tokens	关键输出
Orchestrator	任务分解与分配	0.2	1200	JSON 任务列表
Researcher	多轮检索与相关性评分	0.2–0.3	600–2200	结构化研究笔记
Analyst	证据综合与风险识别	0.35	2200	分析 Markdown
Writer	完整 Markdown 报告生成	0.45	3200	`draft_report`
Reviewer	基于红线的质量审核	0.2	1400	JSON 审核结果
ReviewFeedback	修订简报与闭环验证	0.2	1400–1600	反馈 JSON

Reviewer 红线判定标准

包含 <think> 或内部推理过程 → 不通过
出现无来源的吞吐量/延迟/显存/QPS 数值 → 不通过
使用虚构值制作对比表且未明确标注限制 → 不通过
存在 Web 命中但报告未列出任何 URL 或最新性说明 → 不通过
分数低于阈值（默认 8 分）→ 强制 passed=false

流水线（5 阶段）

任务规划 — Orchestrator 将课题拆解为 3–5 个子任务。
任务执行 — 顺序执行子任务。如果 Writer 在分析完成前执行，自动先调用 Analyst。
补齐草稿 — 确保 analysis_results 和 draft_report 存在后再进入审核。
审核闭环 — Reviewer 评分，ReviewFeedback 制定回退计划，相关 Agent 重新执行。最多重复 max_review_rounds 次。
产物持久化 — 报告、状态、日志、可视化、知识沉淀全部保存到 outputs/。

推理后端

后端	CLI 参数	说明
Direct vLLM	`--backend vllm`	进程内通过 `vllm.LLM()` 加载模型。支持自动模型交换。
OpenAI 兼容	`--backend openai`	连接 vLLM/OpenAI 兼容 HTTP 服务。不在本地加载模型。
Mock	`--backend mock`	确定性响应，用于冒烟测试。无需 GPU。

模型交换机制（V1.1）

当 backend=vllm 且 Agent 使用不同模型路径时，_ensure_agent_model_ready() 自动卸载先前的模型再加载新模型，防止 GPU 显存溢出。

模型目录

模型路径统一为 /mnt/moark-models/。框架内置 9 个模型的目录信息：

模型	能力	推荐 Agent
Qwen3-8B	文本/推理	全部（默认）
Qwen3-4B	文本/快速	Orchestrator, Researcher, ReviewFeedback
Qwen3-0.6B	文本/极快速	Researcher
Qwen3.5-9B	文本/推理	Analyst, Writer, Reviewer
Qwen3.5-27B-W8A8	文本/高质量	Analyst, Writer, Reviewer
Qwen3-30B-A3B-Thinking-2507	思考/高质量	Analyst, Reviewer, ReviewFeedback
Qwen3-VL-4B-Instruct	多模态	Researcher, Reviewer
Qwen3-VL-8B-Instruct	多模态	Researcher, Reviewer
ERNIE-4.5-VL-28B-A3B-Thinking	多模态/思考	Analyst, Reviewer

Agent 模型配置方式：CLI（--agent-model Researcher=Qwen3-4B）、环境变量（METAX_RESEARCHER_MODEL）、JSON 映射（METAX_AGENT_MODEL_MAP）。

多轮检索与知识沉淀

Researcher 执行迭代式检索（默认：3 轮 × 4 查询/轮 × 8 条命中/轮）：

查询生成 — LLM 根据任务生成 4–6 个针对性查询词。
召回 — 查询同时命中 local_search（基于词法、TF）和可选的 web_search（DDGS/Bing 回退）。
相关性评分 — LLM 对结果打分 0–1；词法回退使用 TF 覆盖度 × 2 + 密度。
查询精炼 — LLM 根据信息缺口生成下一轮聚焦查询。
综合 — 保留的高相关结果整理为给 Analyst 的结构化摘要。
知识沉淀 — 查询、摘要和 Top 来源持久化到 data/knowledge/refined/*.md，刷新语料索引。

# 自定义检索参数
python run.py \
  --retrieval-rounds 5 \
  --retrieval-queries-per-round 6 \
  --retrieval-max-hits-per-round 10 \
  --retrieval-relevance-threshold 0.3 \
  --knowledge-refine \
  --topic "..."

质量闭环

Reviewer（score, passed, required_fixes）
    │
    ▼
ReviewFeedback（should_revise, target_agents, backtrack_plan）
    │
    ├── Researcher  ← 证据缺口、来源不足、最新性缺失
    ├── Analyst     ← 逻辑冲突、置信度不足、推断缺口
    └── Writer      ← 结构、引用、表达、完整性
    │
    ▼
validate_closure（closed, final_decision, remaining_risks）
    │
    ├── closed=true 且 should_revise=false → 最终报告
    └── 否则 → 下一轮审核

默认：最多 3 轮修订，通过分数线 8。所有回退动作记录在 quality_actions.json 中。

输出产物

每次运行在 outputs/<timestamp>_<topic>/ 下生成：

文件	说明
`report.md`	最终 Markdown 报告
`state.json`	完整运行状态（任务、来源、审核、事件）
`config.json`	解析后的运行配置
`model_assignments.json`	Agent 到模型的映射
`llm_calls.json`	所有 LLM 和工具调用日志
`agent_llm_usage.json`	按 Agent 汇总的 LLM 使用统计
`sources.json`	加载的语料文件和检索命中
`review_feedback.json`	每轮审核反馈和修订简报
`validation.json`	闭环验证结果
`quality_actions.json`	审核触发的回退动作记录
`visual/workflow.svg`	Agent 协作流程图
`visual/timeline.svg`	LLM 调用时间线
`visual/llm_usage.svg`	各 Agent LLM 用量图
`visual/feedback_loop.svg`	审核与修订闭环图
`visual/model_assignment.svg`	Agent 模型分配图
`visual/retrieval_strategy.svg`	多轮检索可视化
`visual/dashboard.html`	可交互的运行仪表盘
`data/knowledge/refined/*.md`	持久化精炼知识

配置参考

复制 .env.example 为 .env 后修改：

cp .env.example .env

变量	默认值	说明
`METAX_BACKEND`	`vllm`	后端类型：`vllm`、`openai`、`mock`
`METAX_MODEL_PATH`	`/mnt/moark-models/Qwen3-8B`	Direct vLLM 模型路径
`METAX_MODEL_NAME`	`Qwen3-8B`	OpenAI 兼容 API 模型名
`METAX_GPU_MEMORY_UTILIZATION`	`0.88`	vLLM GPU 显存占用比例
`METAX_MAX_MODEL_LEN`	`8192`	最大上下文长度
`METAX_TEMPERATURE`	`0.6`	采样温度
`METAX_MAX_TOKENS`	`2048`	单次生成最大 Token 数
`METAX_RETRIEVAL_ROUNDS`	`3`	最大检索轮次
`METAX_RETRIEVAL_QUERIES_PER_ROUND`	`4`	每轮最多查询数
`METAX_RETRIEVAL_MAX_HITS_PER_ROUND`	`8`	每轮最多保留命中数
`METAX_RETRIEVAL_RELEVANCE_THRESHOLD`	`0.25`	最低相关性保留阈值
`METAX_MAX_REVIEW_ROUNDS`	`3`	最大审核修订轮次
`METAX_REVIEW_SCORE_THRESHOLD`	`8`	审核通过最低分数
`METAX_ENABLE_WEB_SEARCH`	`false`	是否启用 Web Search
`METAX_KNOWLEDGE_DIR`	`data/knowledge`	本地知识库根目录
`METAX_KNOWLEDGE_REFINE_DIR`	`data/knowledge/refined`	精炼知识输出目录
`METAX_OUTPUT_DIR`	`outputs`	运行产物目录
`METAX_ENABLE_VISUALS`	`true`	是否生成 SVG/HTML 可视化
`METAX_LOG_LEVEL`	`INFO`	日志级别

各 Agent 独立覆盖变量：METAX_ORCHESTRATOR_MODEL、METAX_RESEARCHER_MODEL、METAX_ANALYST_MODEL、METAX_WRITER_MODEL、METAX_REVIEWER_MODEL、METAX_REVIEW_FEEDBACK_MODEL。

项目结构

V1/
├── run.py                          # CLI 入口
├── requirements.txt                # 依赖声明
├── .env.example                    # 环境变量模板
├── generate_pptx.py                # PPTX 报告生成器
├── metax_mas/
│   ├── __init__.py
│   ├── cli.py                      # 命令行参数解析与日志设置
│   ├── api.py                      # FastAPI 服务
│   ├── pipeline.py                 # 端到端多智能体编排
│   ├── agents/
│   │   ├── base.py                 # Agent 基类
│   │   ├── orchestrator.py         # 任务规划
│   │   ├── researcher.py           # 多轮检索
│   │   ├── analyst.py              # 证据分析
│   │   ├── writer.py               # 报告生成与修订
│   │   ├── reviewer.py             # 质量审核
│   │   └── review_feedback.py      # 反馈与闭环验证
│   └── core/
│       ├── config.py               # RuntimeConfig 配置管理
│       ├── llm.py                  # 后端适配器（vLLM/OpenAI/Mock）
│       ├── model_catalog.py        # 模型注册表
│       ├── state.py                # ResearchState 与 TaskStatus
│       ├── tools.py                # 本地语料与 Web 搜索
│       ├── artifacts.py            # 输出物持久化
│       └── visualization.py        # SVG/HTML 仪表盘
├── data/
│   └── knowledge/                  # 本地知识库与精炼知识
├── examples/
│   └── metax_local_notes.md        # 示例资料文档
├── log/                            # 运行日志（自动生成）
└── outputs/                        # 运行产物（自动生成）

部署指南

GPU 显存注意

单进程运行多个大模型需要 V1.1 的自动模型交换机制。
如果显存仍然紧张，可让所有 Agent 使用同一模型，或为不同模型启动独立 vLLM serve 实例，通过 --backend openai 连接。
如有其他进程共享 GPU，降低 --gpu-memory-utilization（如 0.75）。

首次启动耗时

backend=vllm 首次调用包含模型加载、torch.compile 和 CUDA 图捕获的一次性开销。使用 --enforce-eager 可跳过图捕获以加快启动（代价是重复调用吞吐量降低）。

Web Search

通过 --web-search 启用。需要网络连接和 ddgs/duckduckgo_search 包。如果不可用，工具返回空结果，报告会注明限制。

API 模式

uvicorn metax_mas.api:app --host 0.0.0.0 --port 8000

V1.1 鲁棒性改进

问题	修复方案
多模型 GPU 显存溢出	`_ensure_agent_model_ready()` 自动卸载先前模型
单任务失败导致流水线崩溃	改为非致命：记录错误，标记 `FAILED`，继续执行
Stage 3/4 异常导致运行中断	所有回退阶段包裹 `try/except`
无持久化日志	`_setup_logging()` 同时写入 stderr 和 `log/` 目录
非结构化错误输出	自动生成 `error_summary_<ts>.txt`，含完整配置信息
缺少 Tokenizer 配置	`tokenizer_mode` 传递给 `LLM()`

许可证

内部研究用途。MetaX / MAS_Metax。