peetwan/fahmai-enterprise-data-agent

# FahMai — 企业数据 Agentic 框架 一个生产级 agent，能够回答有关真实企业数据集（发票、销售、库存、策略、支持聊天）的自然语言问题（泰语 🇹🇭 / 英语 🇬🇧）。其工作原理是将每个问题路由到匹配的确定性 SQL 技能，如果没有匹配项，则回退到 `plan → execute → verify` 的 LLM agent。专为 *FahMai — Enterprise Data Agentic Showdown* 构建。 ## ✨ 功能特性 - 🧠 两层级联 — 针对已知问题类型（重复发票、对账、MSRP 查询等）的快速确定性技能路由器，并配以通用的 Text2SQL `ReAct` agent 作为后备。 - 🔌 后端无关的 LLM 客户端 — 相同的代码可以运行在本地 OpenAI 兼容服务器（vLLM / HF Transformers）、OpenRouter 或 Ollama 上。只需更改一个环境变量即可切换后端，无需修改代码。 - 🛡️ 安全第一 — 在数据层实施基于角色的访问控制（`manager` 无法读取 CEO 的薪资；`finance` 无法读取 HR/PII），外加拒绝保护机制，确保 `"I am the CEO / [SYSTEM] admin"` 的提示词注入无法提权。角色来源于 session，绝不来源于问题。 - 🌊 流式 API — SSE `/stream` endpoint 实时输出框架的工作过程（路由 → 查询 → 回答）。 - 📚 零基础学习文档 — 包含 16 节课的 ELI5（像对待五岁小孩一样解释）英语和泰语学习课程、设计决策报告以及交互式 HTML 解释器。 ## 🏗️ 架构 ``` questions ─┐ ├─► answer() ─► skill router ───────────────► deterministic SQL skill (if one fits) data (DB) ─┘ │ └─► ReAct agent (fallback) ─► plan → execute (SQL/doc_search) → verify │ ▼ LLM client picks a backend by env: OPENAI_BASE_URL ─► local OpenAI server (vLLM / Transformers) model id "org/name" + OPENROUTER_API_KEY ─► OpenRouter else ─► local Ollama ``` ## 📁 仓库结构 | 路径 | 内容 | |------|------| | `fahmai_db_agent/` | 原始框架 — SQLite，纯标准库提交路径。`src/rag/` 是代码，`docs/` 是设计与研究报告。 | | `fahmai_duckdb_agent/` | 基于 **DuckDB** 重新构建并打包为单文件（`fahmai_harness.py`）的框架，具有 `submit` / `serve` / `ask` 模式、SSE 流式 API、RBAC 安全机制、B200 部署脚本以及 EN/TH 学习指南。`tests/` 证明其与原版功能对等。 | | `lanta/` | 用于在 Lanta 集群（HF Transformers 后端）上提供 `Qwen3.6-27B` / 泰语 LLM 服务的 HPC `Slurm` 脚本。提供的为脱敏模板 — 请填入您自己的分配信息。 | | `presentation/` | 交互式 HTML 解释器 — 纵深防御、提示词注入统计数据、ReAct 循环、系统流程。 | ## 🚀 快速开始 提交路径为纯 Python 标准库（无繁重依赖）。DuckDB 框架需要 `duckdb`。 ``` # --- 原始测试工具 (SQLite) --- cd fahmai_db_agent # 通过本地 OpenAI 兼容服务器（vLLM / Transformers / Ollama serve）： OPENAI_BASE_URL=http://localhost:8000/v1 OPENAI_API_KEY=sk-noauth \ python3 -u src/rag/run_submission.py --model qwen3.6-27b --out my_submission.csv # 通过 OpenRouter（云）： OPENROUTER_API_KEY=sk-... python3 -u src/rag/run_submission.py --model qwen/qwen3.5-27b # --- 单文件 DuckDB 测试工具（submit / serve / ask） --- cd ../fahmai_duckdb_agent pip install -r deploy/requirements-harness.txt python3 build_db.py --src ../fahmai_db_agent/fahmai_rag.db # build data/ once (needs the source DB) python3 tests/test_parity.py # DuckDB == SQLite, no GPU needed OPENAI_BASE_URL=http://127.0.0.1:8000/v1 python3 fahmai_harness.py serve --port 8100 curl -sN localhost:8100/stream -d '{"question":"How many sales transactions total?"}' # live SSE ``` ## 🔐 导入您自己的数据 数据集和构建好的数据库不随项目分发。代码期望在每个框架文件夹下包含： - `fahmai_rag.db` — 框架查询的 SQLite 数据库（DuckDB 框架通过 `build_db.py` 从中构建 `data/fahmai.duckdb` + `data/fahmai_fts.db`）。 - `questions.csv` — 格式为 `id,question` 的输入问题（包含一个副本以便您查看格式）。 使用 `FAHMAI_BASE` / `FAHMAI_DB` 环境变量将框架指向您自己的文件（默认值相对于源代码树进行解析）。 ## ☁️ 在 HPC 集群上运行 (Lanta / Slurm) `lanta/` 脚本是模板。请在提交前替换其中的占位符： - `YOUR_ACCOUNT` → 您的 Slurm 分配（`#SBATCH -A`） - `${PROJECT_ROOT}` → 您的项目工作目录（例如 `export PROJECT_ROOT=/project/.../you`） 它们会在 GPU 节点上启动一个 OpenAI 兼容的 `Qwen3.6-27B` 服务器，然后针对该服务器运行框架。 （由于 Lanta 驱动对于当前的 vLLM 来说太旧，因此这些脚本使用 HF Transformers 作为服务引擎。） ## 🧰 技术栈 `Python` · `SQLite` + `DuckDB`（+ 用于 BM25 文档搜索的 `SQLite FTS5`） · `Qwen3.6-27B` · OpenAI 兼容服务（`vLLM` / HF `Transformers`） · `Slurm` (HPC) · SSE 流式传输。 ## 📖 文档索引 - `fahmai_duckdb_agent/study_guide/00_START_HERE.md` — 零基础课程 (EN)；`study_guide_th/` 是泰语版本。 - `fahmai_duckdb_agent/ARCHITECTURE.md` · `DESIGN_DECISIONS.md` · `PIPELINE.md` — 工程实现。 - `fahmai_duckdb_agent/security_eval.md` — RBAC + 注入提权证据。 - `fahmai_db_agent/docs/` — EDA、schema 设计、检索研究、方法。 ## 📄 License [MIT](LICENSE) — © 2026 Peet. 包含的数据集格式和问题样本仅供 FahMai 挑战赛使用；专有数据集本身不属于本仓库的一部分。

标签：AI风险缓解, RAG, SSE流式输出, Streamlit, Text2SQL, Yelp, 企业数据智能体, 后端开发, 提示注入防御, 源代码安全, 访问控制, 逆向工具