智研 ZhiYan：法规与文献检索/对比工作流（内部工具）
整合法规检索、中美监管对比、证据链审计与文献研读，支持 RAG 闭环与本地化部署；数据与向量库均存于本地，便于内网与合规场景使用。
- 中美对比：按主题检索 CN/US 法规片段，生成结构化对比表与监管严苛度评分（1–10），支持导出 Markdown 报告。
- 权威检索与闭环：定向站点（FDA/NMPA/EMA 等）智能搜索 → 下载 → 原子化入库 → 仅新 chunk 索引，避免全库重扫。
- 证据链审计：多维科研画像（法规/论文统计、年度分布、机构占比、关键词聚类），结合 LLM 生成缺口分析（临床验证、软件生命周期、算法验证、网络安全等），输出
data/artifacts/library_report.md，并在 UI 中展示与下载。 - 健康审计 UI：启动审计后可直接在界面查看完整报告、下载
AI-ECG_Library_Audit_Report.md；若磁盘已存在报告，可折叠查看「上次审计报告」。
- Gmail 自动化监控：通过 Gmail API 抓取谷歌快讯（Scholar/Patent）未读邮件中的 PDF 链接，自动下载并入库（
ko watch-gmail，可选--once或后台循环）。 - RTX 5060 加速解析：Embedding 与解析优先使用 GPU；兼容 RTX 5060（sm_120）等新架构，显存常驻、避免请求级重载。
- 自动聚类：运行
ko index paper后自动调用论文聚类，基于 title + summary 关键词打标（AI-ECG、LLM、Computer Vision、Medical AI 等），写入data/processed/papers/library_meta.json；已有非 Uncategorized 标签的论文会跳过重算以节省时间。 - 主题筛选与已读状态：UI 侧栏支持按主题筛选、已读/未读标记（
data/user_reading_history.json）、以及中文深度研报生成与缓存（按论文 chunk 生成结构化报告并保存为{doc_id}.report.md）。
- RAG 闭环：Fetch → Ingest → Index → Ask
- Fetch：从 URL 或配置文件批量下载 PDF（
ko fetch），或通过 Gmail 快讯、权威搜索 pipeline 拉取。 - Ingest：PDF 解析为结构化 doc/card + chunks（法规为
doc.json+chunks.jsonl，论文为card.json+chunks.jsonl）。 - Index：chunks 写入 Chroma，采用 Hybrid（BM25 + 向量） 检索，行政信息降权。
- Ask：RegIntel / PaperScout 问答与对比、审计报告生成，均基于上述索引。
- Fetch：从 URL 或配置文件批量下载 PDF（
- 物理隔离的向量库：法规与论文分目录持久化，便于单独清理论文索引或仅更新法规：
- 法规：
data/indexes/vectorstore/regulatory - 论文：
data/indexes/vectorstore/papers
- 法规：
- 本地数据：原始 PDF、处理后的 JSON、向量库、审计报告等均在 本地
data/目录，需用户自行准备或通过内网分发；无默认云端依赖（除可选 LLM API）。
- Python 3.10+
- Windows PowerShell（推荐）或 WSL
cd <仓库根目录>
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -U pip
pip install -e .验证 CLI：
ko --help在仓库根目录创建 .env 文件（可复制 .env.example 后按需修改）。至少配置 LLM 密钥，否则审计、对比、问答等将不可用：
copy .env.example .env
# 编辑 .env，填入 OPENAI_API_KEY 等说明见下方 本地化部署与 .env 及 .env.example 内注释。
终端 1：FastAPI 后端
.\.venv\Scripts\Activate.ps1
uvicorn apps.api.main:app --reload --host 127.0.0.1 --port 8000终端 2：Streamlit 前端
.\.venv\Scripts\Activate.ps1
streamlit run apps/ui/app.py浏览器访问 Streamlit（默认 http://localhost:8501），侧栏可切换 RegIntel 监管对比 与 PaperScout 研究助手。API 文档：http://127.0.0.1:8000/docs。
| 命令 | 说明 |
|---|---|
ko fetch --url <URL> |
单 URL 下载 PDF 到 data/raw/regulatory（按域名落 cn/us/unsorted） |
ko fetch --config |
按 workflows/regintel/configs/sources.yaml 批量下载 |
ko ingest regulatory |
将 data/raw/regulatory 解析为 doc + chunks |
ko index regulatory |
将法规 chunks 写入向量库 |
ko ingest paper -i <path或目录> |
论文 PDF 解析为 card + chunks |
ko index paper |
论文 chunks 入库并自动更新论文分类标签 |
ko ask regintel "问题" |
法规问答（Hybrid 检索） |
ko watch-gmail --once |
Gmail 快讯抓取 PDF 并下载（需先配置 OAuth） |
- 数据存储：所有原始 PDF、处理后的 JSON、向量索引与审计报告均位于 本地
data/目录，不依赖默认云端存储。用户需自行准备法规/论文 PDF，或通过内网/配置文件分发。 - 必须配置 .env：LLM 调用（DeepSeek 等）、部分前端能力依赖环境变量；未配置时相关功能会报错或提示。
- .env.example 模板：仓库提供
.env.example，列出常用变量及说明。部署时请复制为.env并填入实际值（切勿将.env提交到版本库）。
copy .env.example .env
notepad .env| 变量 | 说明 | 示例 |
|---|---|---|
OPENAI_API_KEY |
LLM API 密钥（如 DeepSeek） | sk-... |
OPENAI_BASE_URL |
可选，LLM 接口地址 | https://api.deepseek.com |
HF_ENDPOINT |
可选，HuggingFace 镜像（国内） | https://hf-mirror.com |
KO_EMBED_MODEL |
可选，Embedding 模型 | BAAI/bge-small-zh-v1.5 |
KO_API_BASE |
可选，UI 调用的 API 地址 | http://127.0.0.1:8000 |
HTTP_PROXY / HTTPS_PROXY |
可选，抓取外网 PDF 时使用 | http://... |
| 路径 | 说明 |
|---|---|
data/raw/regulatory/ |
原始法规 PDF（cn / us / unsorted） |
data/processed/regulatory/ |
法规 doc.json + chunks.jsonl |
data/raw/papers/ |
论文原始 PDF（若经 fetch / watch-gmail 等写入） |
data/processed/papers/ |
论文 card.json + chunks.jsonl + library_meta.json |
data/indexes/vectorstore/regulatory |
法规向量库 |
data/indexes/vectorstore/papers |
论文向量库 |
data/artifacts/ |
审计报告等（如 library_report.md） |
data/user_reading_history.json |
论文已读状态（UI 使用） |
- packages/ko_core：配置、类型、路径、哈希、LLM 客户端、审计服务
- packages/ko_ingest：PDF 解析、切块、法规/论文摄取、fetcher、Gmail 监控、论文聚类
- packages/ko_index：Chroma 向量库（sentence-transformers Embedding）
- packages/ko_retrieval：Hybrid 检索（BM25 + 向量）、行政信息降权
- apps/cli：Typer CLI（
ko命令） - apps/api：FastAPI 入口与 RegIntel / PaperScout 路由
- apps/ui：Streamlit 双模态 UI（RegIntel + PaperScout）
- scripts/：cluster_papers、library_audit、seed_regulatory_data、diagnose_system 等
- workflows/regintel/configs/：法规批量下载配置示例
本项目仅供内部或授权场景使用。医疗器械注册与合规决策请以官方法规与审评机构意见为准。