TonguAgent

项目简介

TonguAgent 是一个面向中医舌诊的多智能体可解释诊断框架。系统以舌图像及可选患者信息为输入，联合本地视觉感知、专科 Agent 分析、知识检索、多轮协商、主诊断融合与视觉 grounding，输出结构化证型、候选分数、证据链与诊断报告。项目采用闭集优先的输出协议，以兼顾 benchmark 可评测性、工程可审计性与中医辨证解释性。

当前仓库包含：

• 数据集适配与预处理
• 本地视觉编码与结构化观测生成
• TCM 知识库构建与检索增强推理
• 多 Agent 协商与闭集诊断融合
• FastAPI 接口、Gradio 演示与实验可视化脚本

目录结构

config/                 配置文件
data/                   标准化数据、知识库与输出目录
src/tonguagent/         核心源码
app/                    Gradio 演示
experiments/            实验脚本
visualization/          图表与 LaTeX 表格生成
tests/                  基础测试
TCM-Tongue/             原始数据集

环境要求

• Python 3.10+
• Windows / Linux 均可
• 推荐 CUDA 环境用于训练视觉模型

安装依赖

使用清华镜像：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

如果需要 PyTorch GPU 版本，请先按本机 CUDA 版本安装官方对应 wheel，再执行上面的命令。

快速开始

1. 生成标准化训练清单与处理后图片

python -m src.tonguagent.data.data_pipeline --config config/default_config.yaml build

2. 构建知识库

python -m src.tonguagent.data.knowledge_base_builder --config config/default_config.yaml build

3. 训练视觉编码器

python -m src.tonguagent.models.train_encoder --config config/default_config.yaml

4. 启动 API

uvicorn src.tonguagent.api:app --host 0.0.0.0 --port 8000

5. 启动 Gradio

python app/gradio_demo.py

大模型配置

在 config/model_config.yaml 中配置：

• siliconflow
• qwen_compatible
• deepseek
• local_rule_based
• 未来可扩展的本地兼容服务

默认统一采用 OpenAI Compatible Chat Completions 协议，便于切换供应商。

数据适配说明

TCM-Tongue 是检测数据集，不是现成的结构化舌诊 JSON。本项目在 data_pipeline.py 中完成：

• 读取 COCO 标注
• 将 21 个检测类别映射为整图多标签舌诊特征
• 生成证据框、区域标签、推断的证型标签
• 输出 data/annotations/*.jsonl

当前实现边界

项目已提供完整工程骨架和可运行主流程，但以下部分默认是“可扩展实现”而非开箱即得的论文级效果：

• SAM 分割：未提供权重时自动降级到基于标注框/轮廓的分割
• 视觉编码器：提供训练和推理代码，性能取决于实际训练
• Multi-Agent：支持真实 API 调用，也支持本地规则模式便于离线调试
• 实验脚本：已给出完整流程框架，部分实验依赖训练结果和人工评审文件

常用命令

python -m pytest tests -q
python experiments/exp1_vision_encoder.py --config config/default_config.yaml
python visualization/plot_results.py --results_dir results --output_dir figures