# shijue

**Repository Path**: how-yang/shijue

## Basic Information

- **Project Name**: shijue
- **Description**: ai视觉对话
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 视觉 (Shijue)

**AI视觉对话 — 多模态AI对话应用**

一款基于 React + TypeScript 构建的多模态 AI 对话应用，集成了视觉识别、语音交互、情绪分析、文档检索等能力，支持本地推理与云端 API 双模式。

---

## 项目概述

视觉 是一个面向个人用户的多模态 AI 助手，核心目标是让用户能够通过**视觉、语音、文字**多种方式与 AI 进行自然交互。项目采用**隐私优先**的设计理念，所有本地模型推理均在浏览器端完成，数据不离开用户设备。

### 核心特性

| 特性 | 说明 |
|------|------|
| 🎯 **视觉识别** | 基于 YOLOv8 的实时目标检测，支持 80+ 类物体识别 |
| 🎭 **情绪分析** | 实时面部表情识别，检测 7 种基本情绪状态 |
| 📝 **OCR 文字识别** | 基于 TrOCR 的文字提取，支持中英文识别 |
| 🎙️ **语音交互** | 实时语音识别与合成，支持多种中文语音 |
| 🧠 **多智能体系统** | 4 个专业智能体协同工作，分工处理不同任务 |
| 📚 **RAG 文档检索** | 基于向量嵌入的文档检索增强，支持语义搜索 |
| 💾 **对话记忆** | 自动压缩与检索历史对话，保持上下文连贯 |
| 🔒 **隐私保护** | 本地推理优先，数据不上传云端 |
| 📱 **离线支持** | IndexedDB 本地存储，支持离线使用 |
| ♿ **无障碍功能** | 屏幕阅读器支持、场景叙述、高对比度模式 |

---

## 功能模块

### 1. 视觉识别系统

**YOLO 目标检测**
- 支持多种模型变体：YOLOv8n / YOLOv8s / YOLOv8m / YOLOv8l / YOLOv8x
- 实时检测摄像头画面中的物体
- 可识别 COCO 数据集 80+ 类物体（人物、物品、动物等）
- Web Worker 异步推理，不阻塞主线程

**颜色分析**
- 自动分析画面中的主要颜色分布
- 提取衣着颜色、环境色调

**场景理解**
- 结合检测结果生成自然语言描述
- 支持人物姿态、衣着、环境分析

### 2. 情绪识别系统

- 基于 FER (Facial Expression Recognition) 模型
- 实时检测 7 种情绪：开心、悲伤、愤怒、惊讶、恐惧、厌恶、中性
- Web Worker 异步推理，1 FPS 更新频率
- 情绪结果用于 AI 对话的情感理解

### 3. 语音交互系统

**语音识别 (ASR)**
- 基于 Web Speech API 的实时语音识别
- 支持中文普通话识别
- VAD (语音活动检测) 自动判断说话结束

**语音合成 (TTS)**
- 4 种预设中文语音：小悦、小宇、小雯、小刚
- 支持语速、音调调节
- 可选云端 TTS (ElevenLabs) 增强音质

### 4. 多智能体系统

| 智能体 | 职责 |
|--------|------|
| **VisionAnalystAgent** | 视觉分析专家，处理图像理解、目标检测、场景描述 |
| **DocumentReaderAgent** | 文档阅读专家，处理 RAG 检索、文档解析、知识提取 |
| **SafetyMonitorAgent** | 安全监控专家，检测敏感内容、风险提示 |
| **AccessibilityAgent** | 无障碍专家，生成场景叙述、屏幕阅读器内容 |

智能体通过 `AgentOrchestrator` 协调工作，根据用户请求自动分配任务。

### 5. RAG 文档检索系统

- 基于 `all-MiniLM-L6-v2` 向量嵌入模型
- 支持文档上传、解析、索引
- 语义搜索，返回相关文档片段
- 与对话系统集成，增强 AI 回答质量

### 6. 对话记忆系统

- 自动压缩历史对话（超过 8 轴触发压缩）
- 保留最近 50 条视觉分析记录
- 支持记忆检索，找回历史对话内容
- 记忆摘要用于保持上下文连贯

### 7. 离线与缓存系统

- IndexedDB 本地存储对话、文档、设置
- 离线检测自动切换本地模式
- 请求缓存减少 API 调用
- 视觉分析结果缓存（3 秒 TTL）

### 8. 成本优化系统

- Token 使用统计与可视化
- API 调用频率限制
- 本地推理优先策略
- 智能缓存减少重复请求

---

## 技术架构

### 前端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| **React** | 18.3.1 | UI 框架 |
| **TypeScript** | 5.7.2 | 类型安全 |
| **Vite** | 6.4.2 | 构建工具 |
| **Tailwind CSS** | 4.0.0 | CSS 框架 |
| **Zustand** | 5.0.3 | 状态管理 |
| **Radix UI** | ^1.x | 原子组件库 |
| **Lucide React** | 0.468.0 | 图标库 |

### AI/机器学习

| 技术 | 版本 | 用途 |
|------|------|------|
| **ONNX Runtime Web** | 1.26.0 | 本地模型推理 |
| **@xenova/transformers** | 2.17.2 | Transformer 模型 |
| **YOLOv8** | v8.2.0 | 目标检测 |
| **FER** | - | 情绪识别 |
| **TrOCR** | small-printed | OCR 文字识别 |
| **MiniLM** | L6-v2 | 文本嵌入 |

### 数据存储

| 技术 | 版本 | 用途 |
|------|------|------|
| **idb** | 8.0.3 | IndexedDB 封装 |
| **localStorage** | - | API 密钥存储 |

---

## 项目结构

```
src/
├── components/          # UI 组件
│   ├── accessibility/   # 无障碍组件
│   ├── agent/           # 智能体状态面板
│   ├── analysis/        # 分析结果展示
│   ├── auth/            # 登录注册
│   ├── conversation/    # 对话界面
│   ├── cost/            # 成本统计
│   ├── layout/          # 布局组件
│   ├── media/           # 媒体组件（摄像头、音频）
│   ├── rag/             # 文档上传
│   ├── settings/        # 设置面板
│   └── status/          # 状态指示器
├── config/              # 配置文件
│   ├── ai-services.ts   # AI 服务配置
│   ├── constants.ts     # 常量配置
│   └ env.ts             # 环境变量
├── hooks/               # React Hooks
│   ├── useAgent.ts      # 智能体 Hook
│   ├── useEmotion.ts    # 情绪识别 Hook
│   ├── useMemory.ts     # 对话记忆 Hook
│   ├── useOCR.ts        # OCR Hook
│   ├── useRAG.ts        # RAG Hook
│   ├── useSpeech*.ts    # 语音相关 Hooks
│   ├── useYOLO.ts       # YOLO Hook
│   └── ...
├── services/            # 服务层
│   ├── agents/          # 智能体实现
│   ├── ai/              # AI 服务
│   ├── auth/            # 认证服务
│   ├── media/           # 媒体处理
│   ├── monitoring/      # 性能监控
│   ├── network/         # 网络服务
│   ├── offline/         # 离线服务
│   ├── rag/             # RAG 服务
│   ├── security/        # 安全服务
│   └── tools/           # 智能体工具
├── stores/              # Zustand 状态
├── styles/              # CSS 样式
├── types/               # TypeScript 类型
├── utils/               # 工具函数
├── workers/             # Web Workers
│   ├── embedding.worker.ts
│   ├── emotion.worker.ts
│   ├── ocr.worker.ts
│   └ yolo.worker.ts
├── App.tsx              # 主应用
├── main.tsx             # 入口文件
```

---

## 安装与运行

### 环境要求

- Node.js >= 18.0
- npm >= 9.0
- 现代浏览器（Chrome 90+、Edge 90+、Firefox 90+）

### 安装步骤

```bash
# 克隆项目
git clone https://gitee.com/how-yang/shijue.git
cd shijue

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

### 构建生产版本

```bash
npm run build
npm run preview
```

---

## 配置说明

### API 密钥配置

项目支持多种 AI 服务 API，可在设置面板中配置：

| 服务 | 用途 | 配置方式 |
|------|------|----------|
| **OpenAI** | GPT 对话 | 设置面板 / 环境变量 |
| **DeepSeek** | DeepSeek 对话 | 设置面板 / 环境变量 |
| **Google Cloud Vision** | 云端视觉识别 | 设置面板 / 环境变量 |
| **ElevenLabs** | 云端 TTS | 设置面板 / 环境变量 |

### 环境变量

创建 `.env.local` 文件：

```env
VITE_OPENAI_API_KEY=your_openai_key
VITE_OPENAI_BASE_URL=https://api.openai.com/v1
VITE_OPENAI_MODEL=gpt-4o-mini

VITE_DEEPSEEK_API_KEY=your_deepseek_key
VITE_DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
VITE_DEEPSEEK_MODEL=deepseek-chat

VITE_GOOGLE_CLOUD_API_KEY=your_google_key
VITE_ELEVENLABS_API_KEY=your_elevenlabs_key
```

### YOLO 模型配置

项目支持多种 YOLO 模型变体：

| 模型 | 大小 | 精度 | 速度 | 下载命令 |
|------|------|------|------|----------|
| YOLOv8n | ~13MB | 低 | 快 | `node scripts/download-yolo.js nano` |
| YOLOv8s | ~44MB | 中 | 中 | `node scripts/download-yolo.js small` |
| YOLOv8m | ~95MB | 高 | 中 | `node scripts/download-yolo.js medium` |
| YOLOv8l | ~150MB | 很高 | 慢 | `node scripts/download-yolo.js large` |
| YOLOv8x | ~200MB | 最高 | 慢 | `node scripts/download-yolo.js xlarge` |

默认使用 YOLOv8m（高精度），模型文件放置于 `public/models/` 目录。

---

## 使用指南

### 基本使用

1. **启动应用**：运行 `npm run dev`，打开浏览器访问 `http://localhost:5173`
2. **配置 API**：在设置面板中配置 OpenAI 或 DeepSeek API 密钥
3. **开启摄像头**：点击摄像头按钮，允许浏览器访问摄像头
4. **开始对话**：通过语音或文字与 AI 交互

### 功能演示

**视觉识别**
- 开启摄像头后，AI 会自动识别画面中的物体
- 检测结果实时显示在画面上方
- 可识别人物、物品、动物等 80+ 类物体

**情绪识别**
- 当检测到人脸时，自动分析情绪状态
- 情绪结果用于 AI 对话的情感理解

**语音交互**
- 点击麦克风按钮开始语音输入
- AI 会自动识别语音内容并回复
- 支持语音合成播放回复内容

**文档检索**
- 上传文档到 RAG 系统
- AI 会基于文档内容回答问题

---

## 开发指南

### 运行测试

```bash
npm run test          # 运行测试
npm run test:watch    # 监听模式
npm run test:coverage # 测试覆盖率
```

### 代码规范

```bash
npm run lint    # ESLint 检查
npm run format  # Prettier 格式化
```

### 提交规范

项目采用 Git 提交规范：

- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档更新
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建/工具相关

---

## 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feat/your-feature`)
3. 提交更改 (`git commit -m 'feat: add your feature'`)
4. 推送分支 (`git push origin feat/your-feature`)
5. 创建 Pull Request

### PR 规范

每个 PR 只做一件事，包含：
- **标题**：一句话说明 PR 内容
- **功能描述**：功能作用与使用方式
- **实现思路**：技术选型与核心逻辑
- **测试方式**：如何验证功能正常

---

## 许可证

MIT License

---

## 致谢

- [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics) - 目标检测模型
- [Xenova Transformers](https://github.com/xenova/transformers.js) - Transformer 模型 JavaScript 实现
- [ONNX Runtime Web](https://github.com/microsoft/onnxruntime) - ONNX 模型推理
- [Radix UI](https://radix-ui.com/) - 无障碍组件库
- [Tailwind CSS](https://tailwindcss.com/) - CSS 框架

---

## 联系方式

- **仓库地址**：https://gitee.com/how-yang/shijue
- **问题反馈**：https://gitee.com/how-yang/shijue/issues