data-analysis-iteration

# 知易智能知识管家 ## 任务目标 - 本技能用于：Windows ARM64端侧智能数据工作站，实现数据分析自动化与知识沉淀结构化 - 能力包含： 1. 自然语言查询解析（如"分析上个月销售趋势"） 2. 多格式数据读取（CSV/JSON/Excel/图像） 3. 批量文件处理与自动分类 4. 8-Agent协作分析（锦衣卫总指挥使/密卷房/通政司/监察院/太史阁/刑狱司/参谋司/驿传司） 5. 四色卡片生成（蓝/绿/黄/红） 6. OCR图像文本提取（支持NPU加速） 7. 知识图谱关联（BGE-M3向量检索） 8. 可视化报告生成 9. Agent记忆共享与流转（SQLite数据库） 10. 知识图谱引导应用 - 触发条件：用户上传数据文件或通过自然语言提出分析需求 ## 核心目标 1. **数据分析自动化**：用户自然语言查询触发端侧处理流程 2. **知识沉淀结构化**：生成四色卡片（事实/解释/风险/行动），构建可检索知识图谱 3. **端侧安全与性能**：数据不出域，NPU推理延迟<500ms，本地向量检索响应<100ms ## 前置准备 ### 环境配置 #### Python虚拟环境（venv_arm64） ```bash # 创建ARM64 NPU优化的虚拟环境 python -m venv venv_arm64 # 激活虚拟环境（Windows） venv_arm64\Scripts\activate.bat # 验证Python版本 python --version # 应显示 Python 3.12.10 ``` #### QNN SDK环境配置（Windows ARM64） ```bash # 设置QNN SDK环境变量 set QNN_SDK_ROOT=C:/path/to/qnn/sdk set PATH=%QNN_SDK_ROOT%/bin;%PATH% ``` #### GenieAPIService配置 ```python # GenieAPIService HTTP API配置 GENIE_API_BASE_URL = "http://localhost:8910" ``` #### 模型配置 ```python # 模型路径配置 MODEL_PATHS = { "qwen2.0-7b-ssd": "models/Qwen2.0-7B-SSD-8380-2.34", # 通用推荐 ⭐️ (~450ms) "llama3.1-8b": "models/llama3.1-8b", # 更强推理 (~520ms) "llama3.2-3b": "models/llama3.2-3b", # 最快响应 (~280ms) "crnn-int8": "models/crnn-int8", # NPU OCR模型 (~50ms) } # 使用NPUModelLoader切换模型 from scripts.model_loader import NPUModelLoader # 使用更小模型（更快） loader = NPUModelLoader(model_key="llama3.2-3b") model = loader.load() # 使用NPU OCR from scripts.ocr_npu import NPUCREngine ocr_engine = NPUCREngine(model_path="models/crnn-int8") result = ocr_engine.extract_text_from_image(image_path) ``` #### NPU OCR配置（新增）⭐ ```python # NPU OCR引擎配置 from scripts.easy_ocr_npu import EasyOCRNPU # 初始化EasyOCR NPU引擎（推荐） ocr_engine = EasyOCRNPU(use_mock=False) # 真实NPU模式 # 单张图像OCR result = ocr_engine.ocr_single_image( image_path="./image.jpg", languages=["ch_sim", "eng"] ) # 批量OCR batch_result = ocr_engine.ocr_batch( image_paths=["./image1.jpg", "./image2.jpg"], languages=["ch_sim", "eng"] ) # 获取引擎信息 info = ocr_engine.get_engine_info() ``` ### 依赖说明 ``` pandas>=1.5.0 openpyxl>=3.0.0 pytesseract>=0.3.0 Pillow>=9.0.0 fastapi>=0.104.0 uvicorn>=0.24.0 faiss-cpu>=1.7.4 sentence-transformers>=2.2.0 httpx>=0.25.0 python-multipart>=0.0.6 pydantic>=2.0.0 python-dotenv>=1.0.0 aiofiles>=23.0.0 ``` ### OCR环境配置 ```bash # 安装Tesseract OCR引擎 apt-get install tesseract-ocr tesseract-ocr-chi-sim ``` ### 数据目录准备 ```bash # 创建用户数据目录 mkdir -p ./user-data/ mkdir -p ./knowledge-graph/ ``` ### NPU部署准备（关键） ```bash # 1. 从高通模型广场下载预转换的QNN格式模型 # 2. 使用QAI AppBuilder将微调模型转换为INT8/INT4精度的QNN格式 # 3. 配置多进程架构，支持四色卡片生成器在独立NPU进程中并行推理 ``` ## 8-Agent协作架构（锦衣卫风格） ### Agent分工（ARM64 NPU优化版本） ``` 用户查询 (U) ↓ 锦衣卫总指挥使 (Orchestrator) - NPU核心（Qwen2.0-7B-SSD或llama3.1-8b） ↓ ├─── 密卷房 (Preprocessor) - CPU辅助（规则引擎） ├─── 查询构建与执行 (Query Builder) - 本地代码（Python + DuckDB） ├─── 卡片生成与分类 (Card Classifier) - NPU路由器（超轻量分类模型） └─── 四色卡片生成器家族（并行NPU推理）： ├─── 通政司 (Fact Generator) - NPU，Qwen2-1.5B-INT4 ├─── 监察院 (Interpreter) - NPU，LoRA微调+量化Qwen2-7B ├─── 刑狱司 (Risk Detector) - NPU，规则引擎+Phi-3-mini └─── 参谋司 (Action Advisor) - NPU，CoT提示技术 ↓ 太史阁 (Memory) - 本地数据库+CPU向量检索（BGE-M3 + FAISS/Chroma） ↓ 驿传司 (Reporter) - 前端 + NPU超轻量模型（100M参数）优化报告语言 ↓ 报告输出 ``` ### 详细Agent说明（ARM64 NPU优化版） **1. 锦衣卫总指挥使 (Orchestrator)** - 定位：8智能体体系的最高调度核心，统筹全流程、分配任务、处理异常 - 部署位置：Windows ARM64 + QNN SDK + NPU，运行Qwen2.0-7B-SSD或llama3.1-8b模型 - 核心能力：需求拆解、任务调度、进度监控、异常处置、结果聚合 - 模型选择： - Qwen2.0-7B-SSD (~450ms) - 通用推荐，平衡性能与速度 - llama3.1-8b (~520ms) - 更强推理能力，适合复杂任务 - llama3.2-3b (~280ms) - 最快响应速度，适合简单任务 - 提示词设计：见 [references/8-agent-architecture.md](references/8-agent-architecture.md) **2. 密卷房 (Preprocessor)** - 定位：数据加工智能体，专注原始数据的清洗、格式转换、特征提取 - 部署位置：CPU辅助，运行规则引擎或小模型 - 核心能力：数据清洗、格式转换、特征提取、质量核验 - 提示词设计：见 [references/8-agent-architecture.md](references/8-agent-architecture.md) **3. 查询构建与执行 Agent (Query Builder)** ⭐新增 - 定位：根据结构化条件生成可执行的查询语句（SQL、API调用），从本地数据库获取数据 - 部署位置：本地代码（Python），不依赖AI模型，连接本地SQLite/DuckDB - 核心能力： - 接收来自Orchestrator的JSON查询条件 - 映射到本地数据库的表和字段 - 生成优化的SQL查询 - 执行查询，将结果集（DataFrame）返回给Orchestrator - 技术特点：确定性程序，确保SQL生成的安全性和效率 - 代码位置：见 [agents/query_builder.py](agents/query_builder.py) **4. 卡片生成与分类 Agent (Card Classifier)** ⭐新增 - 定位：分析数据结果，决定需要生成哪几类卡片，并触发对应的卡片生成器 - 部署位置：骁龙NPU，与Orchestrator共享模型或使用超轻量分类模型 - 核心能力： - 基于数据摘要和用户原始问题，判断需要生成哪些类型的分析卡片（四选一或组合） - 路由到对应的卡片生成器 - 四色卡片规则： - 🔵事实卡片：必须生成，总结核心数据事实 - 🟢解释卡片：当数据有显著变化、模式或对比差异时生成 - 🟡风险卡片：当数据触及预设阈值（如增长率< -5%）、发现异常点或潜在问题时生成 - 🔴行动卡片：当问题本身要求建议，或识别出明确风险和机会时生成 - 代码位置：见 [agents/card_classifier.py](agents/card_classifier.py) **5. 通政司 (Fact Generator) - 四色卡片生成器之一** - 定位：事实生成智能体，从预处理数据中提取核心事实，验证事实真实性 - 部署位置：NPU，使用量化后的Qwen2-1.5B-INT4模型 - 核心能力：事实提取、事实验证、事实结构化、事实反馈 - 提示词设计：专注于客观描述，禁止任何推断 - 并行推理：在独立NPU进程中与其他三个卡片生成器并行推理 - 提示词设计：见 [references/8-agent-architecture.md](references/8-agent-architecture.md) **6. 监察院 (Interpreter) - 四色卡片生成器之一** - 定位：解释生成智能体，为事实结论生成可解释的逻辑说明 - 部署位置：NPU，用业务分析语料对Qwen2-7B进行LoRA微调后量化 - 核心能力：逻辑推导、解释可视化、异常解释、解释校验 - 提示词设计：引导"寻找相关性、季节性、外部因素" - 并行推理：在独立NPU进程中与其他三个卡片生成器并行推理 - 提示词设计：见 [references/8-agent-architecture.md](references/8-agent-architecture.md) **7. 太史阁 (Memory)** - 定位：数据存储智能体，统一数据仓库，支持权限管控与版本回溯；提供知识图谱引导应用服务 - 部署位置：CPU辅助，SQLite + BGE-M3模型 + FAISS/Chroma - 核心能力：全量存储、权限调取、版本管理、向量检索、关联分析、知识图谱引导 - 知识图谱引导应用：见 [references/knowledge-graph-application.md](references/knowledge-graph-application.md) - 详细说明：见 [references/knowledge-graph.md](references/knowledge-graph.md) **8. 刑狱司 (Risk Detector) - 四色卡片生成器之一** - 定位：风险检测智能体，基于事实结论检测潜在风险点，评估风险等级 - 部署位置：NPU，结合规则引擎与轻量模型 - 规则引擎：首先用规则（阈值、同比环比）过滤 - 轻量模型：再用Phi-3-mini量化版描述风险性质和可能影响 - 核心能力：风险规则加载、风险识别、风险评级、风险预警 - 并行推理：在独立NPU进程中与其他三个卡片生成器并行推理 - 提示词设计：见 [references/8-agent-architecture.md](references/8-agent-architecture.md) **9. 参谋司 (Action Advisor) - 四色卡片生成器之一** - 定位：行动建议智能体，基于风险结果和解释结论生成可落地的行动建议 - 部署位置：NPU，使用思维链（CoT）提示技术 - 核心能力：建议生成、建议优先级、建议验证、建议优化 - 提示词设计：要求模型按"问题->根因->可选行动->推荐行动"的步骤推理 - 并行推理：在独立NPU进程中与其他三个卡片生成器并行推理 - 提示词设计：见 [references/8-agent-architecture.md](references/8-agent-architecture.md) **10. 驿传司 (Reporter)** ⭐调整定位 - 定位：报告合成与呈现智能体，将零散卡片整合为结构化的、用户友好的最终报告，并驱动前端界面更新 - 部署位置：前端 (React) 与 端侧轻量模型（100M参数级别）结合 - 工作流程： - 接收来自Orchestrator的所有卡片（JSON格式） - 调用前端组件，按照"总览 -> 事实 -> 解释 -> 风险 -> 行动"的逻辑顺序进行排版 - 调用运行在骁龙NPU上的超轻量文本润色模型，对报告的语言进行流畅性优化 - 生成交互式数据看板，支持用户点击卡片钻取详情 - 提示词设计：见 [references/8-agent-architecture.md](references/8-agent-architecture.md) 详细架构说明：见 [references/8-agent-architecture.md](references/8-agent-architecture.md) ### NPU部署策略（关键创新点） **1. 模型量化** - 使用QAI AppBuilder，将微调后的模型转换为INT8/INT4精度的QNN格式 - 在NPU上获得最佳能效比 **2. 并行执行** - 利用QAI AppBuilder的多进程架构 - 让四个卡片生成器（通政司/监察院/刑狱司/参谋司）在独立的NPU进程中并行推理 - 大幅提升处理速度 **3. 模型选择策略** - 根据任务复杂度动态选择模型： - 简单任务：llama3.2-3b (~280ms) - 通用任务：Qwen2.0-7B-SSD (~450ms) - 复杂推理：llama3.1-8b (~520ms) - 通过NPUModelLoader灵活切换 详细部署指南：见 [references/npu-deployment.md](references/npu-deployment.md) ## 操作步骤 ### 标准流程 1. **批量数据加载** - 支持用户拖拽文件夹或选择目录 - 调用 `scripts/batch_process.py --dir <目录路径>` 批量处理 - 自动识别文件类型（CSV/JSON/Excel/图像） - 对图像文件执行OCR提取文本 2. **任务触发与分解** - 用户自然语言查询（如"分析上个月销售趋势"） - **锦衣卫总指挥使**解析意图，拆解为原子任务： * 密卷房数据加工→查询构建与执行→卡片生成与分类→四色卡片并行生成→太史阁知识检索→驿传司报告合成 3. **数据预处理** - **密卷房**接收数据加工任务 - 数据感知：对接多源数据（数据库/API/文件） - 数据清洗：处理缺失值、异常值、重复值 - 格式转换：统一转换为结构化JSON格式 - 特征提取：提取核心分析特征 - 输出"预处理数据+质量报告"至总指挥使 4. **查询构建与执行** - **查询构建与执行 Agent**接收查询条件 - 接收来自Orchestrator的JSON查询条件 - 映射到本地数据库的表和字段 - 生成优化的SQL查询 - 执行查询（使用DuckDB），将结果集（DataFrame）返回给Orchestrator - 输出"查询结果+数据摘要"至总指挥使 5. **卡片生成与分类** - **卡片生成与分类 Agent**接收数据摘要和用户原始问题 - 基于数据摘要和用户原始问题，判断需要生成哪些类型的分析卡片 - 四色卡片规则： * 🔵事实卡片：必须生成，总结核心数据事实 * 🟢解释卡片：当数据有显著变化、模式或对比差异时生成 * 🟡风险卡片：当数据触及预设阈值（如增长率< -5%）、发现异常点或潜在问题时生成 * 🔴行动卡片：当问题本身要求建议，或识别出明确风险和机会时生成 - 输出"需要生成的卡片类型列表"至总指挥使 6. **四色卡片并行生成** ⭐关键创新 - **四色卡片生成器家族**（通政司/监察院/刑狱司/参谋司）并行接收生成任务 - 每个生成器在独立NPU进程中运行，实现并行推理 - **通政司**（事实卡片生成器）：使用Qwen2-1.5B-INT4，专注于客观描述 - **监察院**（解释卡片生成器）：使用LoRA微调+量化Qwen2-7B，引导寻找相关性、季节性、外部因素 - **刑狱司**（风险卡片生成器）：结合规则引擎（阈值、同比环比）+ Phi-3-mini量化版，描述风险性质和可能影响 - **参谋司**（行动卡片生成器）：使用CoT提示技术，按"问题->根因->可选行动->推荐行动"步骤推理 - 输出四色卡片至总指挥使 7. **知识沉淀与关联** - **太史阁**存储新卡片元数据到SQLite - 使用BGE-M3模型将卡片内容向量化 - 存入FAISS/Chroma本地库 - 根据当前查询语义检索相关历史卡片 - 应用四色卡片关联维度： * 蓝色卡片（事实层）：时间/地点/人物/事件/数字指标 * 绿色卡片（分析层）：因果关系/对比关系/趋势变化/关联规则 * 黄色卡片（创意层）：跨领域类比/潜在机会/创新方向 * 红色卡片（风险层）：潜在问题/负面因素/冲突矛盾 - 支持自定义关联规则： * 显性规则：直接描述关联逻辑（"将销售额>100万的地区与营销策略关联"） * 隐性规则：通过示例学习关联模式 * 规则优先级：指定不同规则的权重和执行顺序 - 跨色卡片引用机制： * 直接引用：任意卡片可引用其他颜色卡片 * 规则映射：通过自定义规则实现跨色关联 * 动态更新：引用关系随原始节点变化自动更新 * 引用限制：循环引用检测、权限控制、引用标记 - 详细说明：见 [references/knowledge-graph.md](references/knowledge-graph.md) 和 [references/card-specification.md](references/card-specification.md) 8. **报告合成与呈现** ⭐调整 - **驿传司（Reporter）**接收所有四色卡片 - 调用前端组件，按照"总览 -> 事实 -> 解释 -> 风险 -> 行动"的逻辑顺序进行排版 - 调用运行在骁龙NPU上的超轻量文本润色模型（100M参数级别），对报告的语言进行流畅性优化 - 生成交互式数据看板，支持用户点击卡片钻取详情 - 输出格式：见 [assets/data-analysis-report-template.md](assets/data-analysis-report-template.md) ### 端到端分析示例 **场景：销售数据分析（用户查询："分析上个月销售趋势"）** 1. **任务触发** - 锦衣卫总指挥使解析意图为"趋势分析"，启动标准流程 2. **数据预处理** - 密卷房输出预处理数据： ```json { "preprocessed_data": { "data": [ {"date": "2024-12-01", "sales": 50000}, {"date": "2024-12-31", "sales": 42500} ] }, "quality_report": { "completeness": 0.98, "accuracy": 0.99 } } ``` 3. **事实生成** - 通政司输出事实结论： ```json { "fact_card": { "card_type": "blue", "title": "12月销售数据统计", "content": { "dimensions": ["时间"], "metrics": { "sales": {"value": 1200000, "unit": "元"}, "growth_rate": {"value": "-15%", "comparison": "环比"} } } } } ``` 4. **解释生成** - 监察院输出解释说明： ```json { "interpretation_card": { "card_type": "green", "title": "销售下滑原因分析", "content": { "logic_chain": [ {"step": 1, "description": "竞品于12月中旬推出满减促销活动"}, {"step": 2, "description": "核心客户群体被分流"}, {"step": 3, "description": "销量环比下降15%"} ] } } } ``` 5. **风险检测** - 刑狱司输出风险结果： ```json { "risk_card": { "card_type": "yellow", "title": "库存积压预警", "content": { "risk_type": "库存积压", "risk_level": "一级", "details": { "current_stock": 5000, "expected_demand": 2000, "excess_ratio": "150%" } } } } ``` 6. **行动建议** - 参谋司输出行动建议： ```json { "action_card": { "card_type": "red", "title": "库存清理行动建议", "content": { "actions": [ { "step": 1, "action": "推出限时折扣清理库存", "priority": "立即执行",