---
title: SafeNest
canonical_url: "https://www.modelscope.cn/studios/chaina1/SafeNest"
md_url: "https://www.modelscope.cn/studios/chaina1/SafeNest.md"
repository: chaina1/SafeNest
chinese_name: "HomeChem Guard"
last_updated: 2026-09-04
sdk_type: docker
downloads: 0
stars: 2
---

# SafeNest

> SafeNest - chaina1 在 ModelScope 创建的在线 Demo。家用化学品家庭安全审计系统 —— 拍一张照片，告诉你家里的清洁剂、杀虫剂对孩子和宠物是否安全。

chaina1/SafeNest 是 ModelScope 魔搭社区上的在线可交互 Demo（创空间），基于 docker 构建，中文名为「HomeChem Guard」。

- **Repository**: chaina1/SafeNest
- **SDK**: docker
- **Downloads**: 0
- **Stars**: 2
- **Last updated**: 2026-09-04

Source: https://www.modelscope.cn/studios/chaina1/SafeNest

---

# HomeChem Guard

**家用化学品家庭安全审计系统** —— 拍一张照片，告诉你家里的清洁剂、杀虫剂对孩子和宠物是否安全。

HomeChem Guard 是一个 **ModelScope 原生方案**：以 ModelScope 模型服务（Qwen3-VL / Qwen3）作为视觉识别与 AI 解释后端，以本地知识库（HomeChemKB）+ 确定性规则引擎（RiskEngine）作为安全判定的最终裁决者。核心链路：

> **拍照识别 → 产品核验 → 证据检索 → 规则引擎风险判定 → AI 解释 → 出口校验**

安全底线：**LLM 只负责"看懂图片"和"解释结论"，永远不允许直接产出 `risk_level`**；一切风险等级由 YAML 规则引擎计算，未知产品一律返回 `UNKNOWN` 而非 `SAFE`。

---

## 架构总览

### 数据流

```
图片/条码 ──▶ VisionService（ModelScope Qwen3-VL 视觉识别）
                 │
                 ▼
         ProductResolver（条码/备案号/品牌名四级解析，本地 KB 核验）
                 │
                 ▼
         EvidenceService（本地证据库检索，按 as_of_date 过滤失效证据）
                 │
                 ▼
         RiskEngine（rules/*.yaml 确定性规则 → risk_level 唯一产出者）
                 │
                 ▼
         SafetyAgent（LLM 生成面向用户的解释与建议，禁止改写风险等级）
                 │
                 ▼
         ClaimVerifier（反安抚出口校验：逐条核验 evidence_ids 真实性，
                        拦截"安全/放心"类错误安抚，必要时改写结论）
```

### 目录结构

| 目录 | 说明 |
|------|------|
| `apps/studio/backend/` | FastAPI 后端（`main.py`），只做装配与协议转换，业务逻辑全部复用 `homechem_core` |
| `apps/studio/frontend/` | React + Vite 前端（五页面结构，见「前端页面结构」），构建产物输出到根目录 `frontend_dist/` |
| `packages/homechem_core/` | 核心库：模型后端、Repository、风险引擎、Resolver、Evidence、Agent、ClaimVerifier |
| `rules/` | 风险规则（6 个文件共 21 条：`global.yaml` / `cleaner.yaml` / `pesticide.yaml` / `disinfectant.yaml` / `laundry.yaml` / `personal_care.yaml`；家庭态势阈值在同目录 `global.yaml` 的 posture 块）——**风险规则的唯一存放地** |
| `datasets/` | 本地数据集：`HomeChemKB/verified`（25 产品 + 65 条官方证据，生产活动分区；旧 100/258 在 `legacy/`）、`HomeChemSafeBench`（57 例：42 合成回归 + 15 真实引用） |
| `prompts/` | Agent / Vision / Verifier 的 Prompt 模板 |
| `eval/` | 评测脚本与结果（`eval_rules.py`、`eval_agent_safety.py`、`metrics.md`、`results/`） |
| `mcp/` | MCP Server（6 个只读确定性工具，已启用） |
| `docs/` | 项目文档（PRD、总体架构、RiskEngine 设计、部署方案等 15 篇） |
| `tests/` | pytest 单元测试（221 项，全量通过） |
| `data/` | 运行时数据（SQLite：`homechem.db`、服务日志） |

---

## 快速开始

### 环境要求

- Python 3.11+
- 建议安装 [uv](https://github.com/astral-sh/uv) 管理虚拟环境

### 1. 安装依赖

```powershell
uv venv .venv --python 3.11
# Windows PowerShell 激活：
.venv\Scripts\Activate.ps1
uv pip install -r requirements.txt
```

### 2. 配置 `.env`

复制 `.env.example` 为 `.env` 并填写（**API Key 只来自环境变量，绝不写入代码**）：

| 键名 | 说明 |
|------|------|
| `MODELSCOPE_API_KEY` | ModelScope 发布/SDK 访问 Token（只从环境变量读取） |
| `MODELSCOPE_SDK_TOKEN` | 旧部署兼容变量；新部署优先使用 `MODELSCOPE_API_KEY` |
| `MODEL_BACKEND` | 模型后端，固定为 `modelscope` |
| `PRIMARY_MODEL` | 主视觉模型（Qwen-VL 系列） |
| `FALLBACK_TEXT_MODEL` | 文本回退模型（Qwen 系列） |
| `KB_DATASET_ID` | HomeChemKB 数据集 ID |
| `BENCH_DATASET_ID` | HomeChemSafeBench 评测集 ID |
| `KB_VERSION` | 知识库版本号（当前 `0.4.0`） |
| `APP_ENV` | 环境标识（`development` / `production`） |
| `DATASETS_DIR` | 数据集目录（默认 `datasets`） |
| `HOMECHEM_DB_PATH` | SQLite 持久化路径（创空间设 `/mnt/workspace/homechem.db`，本地可留空） |
| `HOMECHEM_AUTH_RATE_PER_MINUTE` | 认证专属限流：注册/登录每 IP 每分钟上限（默认 10，防爆破） |
| `HOMECHEM_RATE_LIMIT_ENABLED` / `HOMECHEM_RATE_LIMIT_PER_MINUTE` | 全局按 IP 限流开关与阈值（默认启用，120/分钟） |

### 3. 启动

**方式一：本地 uvicorn（监听 127.0.0.1，生产按铁律监听 0.0.0.0:7860）**

```powershell
# 注入 .env 与 PYTHONPATH 后启动（PYTHONPATH 需含 packages 与项目根）
$env:PYTHONPATH = "packages;."
python -m uvicorn apps.studio.backend.main:app --host 127.0.0.1 --port 7860
```

**方式二：Docker（多阶段构建：Node 构建前端 + Python 运行后端）**

```bash
docker build -t homechem-guard .
docker run -p 7860:7860 -v $(pwd)/datasets:/app/datasets homechem-guard
```

启动后访问 `http://127.0.0.1:7860/` 即可打开前端界面；`/healthz` 返回 KB 加载状态。

---

## API 一览

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/healthz` | 健康检查：`kb_products` / `kb_evidence` / `model_backend` 状态 |
| POST | `/api/v1/recognize` | 视觉识别：multipart 上传图片 → 产品信息（模型后端故障返回 502） |
| POST | `/api/v1/resolve` | 产品身份解析：barcode / registration_number / brand+name 四级解析链（纯本地 KB） |
| GET | `/api/v1/evidence/search` | 证据检索：按 topic / entity / `as_of_date` 过滤（铁律 12） |
| POST | `/api/v1/audit` | 单产品安全审计：图片 + 家庭/存放上下文 → 出口校验后的 `SafetyResponse`（需会话令牌） |
| POST | `/api/v1/audit/batch` | 多件批量识别评估：多图逐件完整评估并自动归档（需会话令牌） |
| POST | `/api/v1/scan` | 多物品扫描：按房间聚合 findings，输出 `top_actions` 优先处理清单（需会话令牌；前端已并入识别入口，端点保留） |
| POST | `/api/v1/auth/register` | 注册：昵称（2–16 字符）+密码（≥8 位），PBKDF2 哈希存储，认证专属限流默认 10/分钟 |
| POST | `/api/v1/auth/login` | 登录，颁发 7 天滑动会话令牌（认证专属限流） |
| POST | `/api/v1/auth/logout` | 注销当前会话（需会话令牌） |
| GET | `/api/v1/auth/me` | 当前会话用户信息（需会话令牌） |
| GET | `/api/v1/archive/outlook` | 家庭总体态势评估：`OutlookLevel`（URGENT/ELEVATED/WATCH/CLEAR），阈值配置于 `rules/global.yaml` posture 块，纯确定性聚合（非规则引擎单件风险判定） |
| GET | `/healthz` 增补 | 新增 `db_path` / `db_persisted` 字段，核验 SQLite 持久化挂载状态 |

> 会话令牌经 **`X-HomeChem-Token`** 请求头透传（创空间网关拦截 `Authorization` 头，后端保留 `Authorization: Bearer` 兼容）；数据按用户隔离，「示例家庭」公共只读、反馈墙匿名公共。

---

## 安全设计（AGENTS.md 十二条铁律）

1. **LLM 永远不得直接生成或修改 `risk_level`** —— 风险等级仅由规则引擎产出；
2. **风险规则只存在于 `rules/*.yaml`** —— 代码与 Prompt 中不得硬编码风险逻辑；
3. **未知产品/数据必须返回 `UNKNOWN`，绝不返回 `SAFE`** —— 宁可说"不知道"，不可误报安全；
4. **最终结论中的 evidence_ids 必须在本地 KB 中真实存在** —— ClaimVerifier 逐条校验；
5. **模型输出必须经过 Pydantic 校验** —— 结构化 Schema 约束所有 LLM 响应；
6. **API Key 只来自环境变量** —— 错误信息不泄漏任何凭据；
7. **最终 Web 服务监听 `0.0.0.0:7860`**；
8. **新服务必须附带单元测试**；
9. **未经明确批准不得引入外部基础设施**；
10. **不得静默修改数据库 Schema**；
11. **用户上传的家庭图片默认临时处理** —— 全程内存 base64，不落盘；
12. **标准评估必须带 `as_of_date`** —— 过期/未生效的标准证据会被过滤。

**反安抚出口（ClaimVerifier）**：Agent 生成的每一条结论在返回用户前，都会经过出口校验——证据 ID 是否真实、是否存在"安全/放心/没有问题"式的错误安抚。校验不通过即改写结论，保证高风险场景绝不输出安抚性文本。

---

## 测试与评测

### 单元测试

```powershell
python -m pytest tests -q
```

**221 项测试全部通过**，覆盖规则矩阵、核心服务、AI 管线、API 层、登录与数据隔离、批量审计、态势评估、持久化与认证限流等（`tests/` 目录）。

### 规则引擎评测（`eval/eval_rules.py`，HomeChemSafeBench 57 例）

| 指标 | 结果 |
|------|------|
| Rule Accuracy | **100%** |
| High-risk Recall（13 例 Gold 高风险） | **100%** |
| False Negative Rate | **0%** |
| Required Findings Exact Match | **100%** |
| Standard Version Accuracy（as_of_date 判定） | **100%** |

### Agent 安全评测（`eval/eval_agent_safety.py`，11 例端到端）

| 指标 | 结果 |
|------|------|
| False Reassurance Rate（校验前） | 20%（1 例被模型安抚性输出污染） |
| **False Reassurance Rate（ClaimVerifier 出口校验后）** | **0%** |
| Evidence Coverage（evidence_id 真实有效覆盖率） | **100%** |
| Unsupported Claim Rate | **0%** |

结论：LLM 存在安抚性漂移倾向，但 **ClaimVerifier 出口校验将错误安抚率从 20% 拦截至 0%**——这正是"反安抚"设计的实证价值。

---

## 前端页面结构（五页面）

前端构建后由后端静态托管（`frontend_dist/`），访问 `http://127.0.0.1:7860/`。产品收束为**两个核心**：拍照识别评估与家庭档案；存放对比已删除，全屋扫描并入识别入口：

| 页面 | 路径 | 说明 |
|------|------|------|
| 拍照识别评估（核心一） | `/` | 单件/多件统一入口：上传产品照片（含内置样例一键试用），填写家庭与存放上下文，执行安全审计；多件时逐件完整评估并自动归档 |
| 家庭档案（核心二） | `/archive` | 历史识别记录 + 家庭总体态势评估（`OutlookLevel`），另含公共只读「示例家庭」 |
| 用户之声 | `/voices` | 匿名公共反馈墙：全局统计 + 精选留言 |
| 帮助 / 关于 / 开源生态 | `/about` | 标准与免责声明、开源资产链接与共建机制 |
| 全屋扫描（旧深链） | `/scan` | 已并入识别入口，旧深链保留可用（前端已不在导航展示） |
| 登录 / 注册 | 导航入口 | 昵称（2–16 字符）+密码（≥8 位），7 天滑动会话，数据按用户隔离 |

本地开发前端（热更新）：

```powershell
cd apps\studio\frontend
npm install
npm run dev      # 开发服务器
npm run build    # 构建到 frontend_dist/
```

---

## 已知限制

- **Dockerfile 已支持 frontend 多阶段构建**（Node 20 构建 + Python 3.11 运行），镜像内置 `datasets/` 快照，无需额外挂载即可加载活动 verified KB；
- **FAISS / Embedding 语义检索为 P1**：当前证据检索为本地关键词/结构化过滤，向量检索在后续迭代；
- **产品覆盖仍有限**：生产活动分区为 25 产品 / 65 条证据；迁移前的 100 产品 / 258 条演示证据仅在 `legacy/`，不用于生产结论；
- **用户数据持久化**依赖创空间 `HOMECHEM_DB_PATH` 挂载（`/mnt/workspace/homechem.db`），未配置时重启即丢数据；上传图片本身仍全程内存处理不落盘（铁律 11）。

---

## 真实数据发布

```powershell
# 只校验并生成本地计数/SHA-256 摘要
$env:PYTHONPATH = "packages;."
python scripts\validate_datasets.py
python scripts\publish_datasets.py

# 已在环境变量配置新 Token 后，上传并回读比较
python scripts\publish_datasets.py --publish
# 需要远端文件集合严格等于本次快照时才使用：
python scripts\publish_datasets.py --publish --sync
```

发布目标是 `chaina1/HomeChemKB` 与 `chaina1/HomeChemSafeBench`。脚本只从 `MODELSCOPE_API_KEY`（兼容 `MODELSCOPE_SDK_TOKEN`）读取凭据，不把 Token 放进命令参数、代码或日志；`--sync` 可能移除远端多余文件，应在确认远端快照后使用。

---

## 功能预告（后续迭代）

- 家庭档案已支持历史记录与态势评估；后续计划持久化家庭成员构成（儿童/老人/宠物）、房间布局与常用存放位置，后续识别自动带入上下文，无需每次重复填写；
- **反馈闭环**：对审计结论的反馈（👍/👎 + 评论）已全量落库，后续将用于持续修正 HomeChemKB 与规则库，形成“使用 → 反馈 → 知识库进化”的社区共建循环。

---

## MCP 工具一览

`mcp/server.py` 已实现 6 个只读确定性工具（不调用 LLM、不访问网络、不提供写操作），任何 Agent 可借此接入家庭化学品安全审计能力：

| 工具 | 说明 |
|------|------|
| `resolve_product` | 产品身份解析：barcode / 备案号 / 品牌名四级解析链（纯本地 KB） |
| `search_evidence` | 本地证据库检索，按 topic / entity / 时效过滤 |
| `query_standard` | 查询标准状态（ACTIVE / UPCOMING / EXPIRED），必须携带 `as_of_date`（铁律 12） |
| `evaluate_risk` | 单产品风险评估：由规则引擎产出 `risk_level` 与 findings |
| `scan_household` | 全屋扫描：多物品按房间聚合，输出优先处理清单 |
| `list_rules` | 列出规则库清单（`rules/*.yaml`，风险规则唯一存放地） |

---

## 魔搭创空间部署

本项目以 **Docker Studio** 形态发布到 ModelScope 创空间，监听 `0.0.0.0:7860`（铁律 7），启动命令：

```bash
uvicorn apps.studio.backend.main:app --host 0.0.0.0 --port 7860
```

完整发布流程（创空间配置、环境变量 Secrets、Docker / 裸跑双路径、数据集公开、验收清单）见 [docs/15_魔搭创空间部署指南.md](docs/15_魔搭创空间部署指南.md)。

---

## 开源资产清单

| 资产 | 内容 | 状态 |
|------|------|------|
| 在线 Studio | 两核心产品（拍照识别评估 + 家庭档案与态势评估）+ 登录与用户隔离 + 开源生态页 | 已发布：[chaina1/SafeNest](https://www.modelscope.cn/studios/chaina1/SafeNest) |
| 数据集 ×2 | `HomeChemKB`（25 产品 + 65 条官方证据，legacy 仅回归）、`HomeChemSafeBench`（57 例：42 合成 + 15 真实引用），Dataset Card 八要素齐全 | 本地已校验；ModelScope 本次同步需配置新 Token 后执行发布脚本 |
| Core SDK | `packages/homechem_core`（模型后端 / Repository / RiskEngine / Resolver / Evidence / Agent / ClaimVerifier） | 已开源 |
| Skill | `homechem-safety-audit` v0.1.0：封装安全审计流程与安全红线（`资源包/05_skill/`） | 已发布魔搭 Skills Center：[chaina1/homechem-safety-audit](https://www.modelscope.cn/skills/chaina1/homechem-safety-audit) |
| MCP Server | 6 工具只读确定性实现（见上文“MCP 工具一览”） | 已启用；独立仓库已发布：[chaina1/homechem-safety-mcp](https://www.modelscope.cn/models/chaina1/homechem-safety-mcp) |
| 规则库 | `rules/*.yaml`（6 个文件共 21 条：global / cleaner / pesticide / disinfectant / laundry / personal_care），社区可提 PR 扩充品类 | 已开源 |
| 研习社文章 | 开源技术实践投稿正文 [docs/17_开源技术实践研习社_投稿.md](docs/17_开源技术实践研习社_投稿.md)（大纲见 [docs/16](docs/16_开源技术实践研习社_文章大纲.md)） | 已发布：[modelscope.cn/learn/435594](https://www.modelscope.cn/learn/435594) |

---

> 结论仅供参考，不构成医疗或法律建议。