# snail-ai **Repository Path**: wb6class/snail-ai ## Basic Information - **Project Name**: snail-ai - **Description**: snail-ai基于LangChain进行项目实战，主要应用于Snail管理系统包括系统知识库、智能运维机器人等等（后续会Snail项目中同步开发Java版本），不断更新中...... - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 5 - **Created**: 2026-06-04 - **Last Updated**: 2026-06-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Snail AI 🐌 **智能蜗牛** — 一个 Java 转 Python 学习实践 + 人工智能对话助手项目。 > 从「基础概念映射」到「AI 智能对话」，见证一条完整的 Python 成长曲线。 --- ## 📦 项目构成 本项目包含两个独立的子项目： ### 1. `py_study_fastapi` — Python 学习实践（FastAPI 用户管理 CRUD） 从 Java 开发者的视角出发，系统性学习 Python、FastAPI、SQLAlchemy 等 Web 后端技术栈。 - **Web 框架**: FastAPI + Uvicorn - **ORM**: SQLAlchemy 2.0 + PyMySQL（MySQL） - **数据验证**: Pydantic / Pydantic-Settings - **密码安全**: Passlib + Bcrypt - **前端**: 纯 HTML/CSS/JS 单页应用（用户管理界面） - **端口**: 8000 **配套学习文档**（`docs/Java转Python学习文档/`）： | 天次 | 内容 | |------|------| | 第1天 | 基础概念映射（Java → Python） | | 第2天 | FastAPI 框架入门 | | 第3天 | SQLAlchemy ORM | | 第4天 | 异步编程 | | 第5天 | 异常与日志 | | 第6天 | 项目实战 — 用户管理（CRUD + 前端联调） | | 第7天 | AI 应用 — 基础概念 | | 第8天 | AI 应用 — Milvus 向量数据库 | --- ### 2. `snail-ai-oamr` — AI 智能聊天助手 基于 LangGraph 工作流的多 Agent 对话系统，支持问题分类、RAG 知识检索、流式 SSE 输出。 - **LLM 模型**: 通义千问（DashScope）— qwen3-max - **嵌入模型**: text-embedding-v4 - **工作流引擎**: LangGraph（状态图 + 条件路由） - **向量数据库**: Milvus（port 19530） - **检索策略**: 混合检索（向量语义 + BM25 关键词） - **中文分词**: jieba - **前后端通信**: SSE（Server-Sent Events）流式输出 - **前端**: 深色主题 AI 聊天界面 - **端口**: 8100 **Agent 工作流**： ``` 用户输入 → 保存记忆 → 问题分类 ├── 闲聊 → 闲聊Agent ├── 业务问题 → 业务QA Agent（可接 RAG） ├── 业务操作 → 操作Agent ├── 系统问题 → 系统诊断Agent └── 数据统计 → 数据统计Agent ↓ 保存回复 → 输出 ``` --- ## 🏗️ 项目结构 ``` snail-ai/ ├── README.md # ← 本文档 ├── LICENSE # MIT ├── docs/ # 学习文档 │ ├── 第1天~第8天.md # 学习日课 │ └── Java转Python学习文档/ # Java 视角版 │ ├── py_study_fastapi/ # 🅰️ Python 学习 — FastAPI CRUD │ ├── requirements.txt │ ├── .env # 数据库配置（参考 .env.example） │ ├── app/ │ │ ├── main.py # 应用入口 + 全局异常处理 + CORS │ │ ├── core/ │ │ │ ├── config.py # Pydantic Settings 配置管理 │ │ │ ├── database.py # SQLAlchemy 引擎 & Session │ │ │ ├── exceptions.py # 自定义业务异常 │ │ │ └── logger.py # 日志配置 │ │ ├── models/ │ │ │ └── user.py # ORM 模型（SysUser） │ │ ├── schemas/ │ │ │ └── user.py # Pydantic 请求/响应模型 │ │ ├── services/ │ │ │ └── user.py # 业务逻辑层 │ │ ├── api/v1/ │ │ │ └── user.py # RESTful 路由 │ │ └── utils/ │ │ └── response.py # 统一响应格式 │ └── static/ │ └── index.html # 用户管理前端页面 │ └── snail-ai-oamr/ # 🅱️ AI 智能聊天助手 ├── frontend/ │ └── index.html # AI 聊天前端（深色主题） └── backend/ ├── requirements.txt ├── main.py # FastAPI 入口（SSE 流式接口） ├── service.py # ChatService 业务编排 ├── config/ │ ├── oamr.yml # 模型配置（chat/embeddings） │ ├── prompts.yml # 提示词文件路径 │ └── vector_store.yml # Milvus 向量库配置 ├── prompts/ # Agent 提示词（.txt） ├── base/ │ └── state_models.py # 状态定义（AgentState / ClassificationResult） ├── graph/ │ ├── workflow.py # LangGraph 工作流编排 │ └── agent.py # 各 Agent 实现（分类/闲聊/业务等） ├── model/ │ └── factory.py # 模型工厂（ChatTongyi / DashScopeEmbeddings） ├── rag/ │ ├── vector_store.py # Milvus 向量存储（纯向量检索） │ ├── hybrid_retriever.py # 混合检索（向量 + BM25） │ └── RAG检索问题.md # RAG 优化分析 └── utils/ ├── config_handler.py # YAML 配置加载 ├── path_tool.py # 路径工具 ├── prompt_loader.py # 提示词加载 └── logger_handler.py # 日志处理 ``` --- ## 🚀 快速开始 ### 前提 - Python 3.9+ - MySQL（py_study_fastapi 需要） - Milvus 向量数据库（snail-ai-oamr 需要） - DashScope（通义千问）API Key --- ### 1️⃣ 启动用户管理 CRUD（py_study_fastapi） ```bash cd py_study_fastapi # 安装依赖 pip install -r requirements.txt # 配置数据库（编辑 .env 或设置环境变量） # DB_HOST=localhost DB_PORT=3306 DB_USER=root DB_PASSWORD=... DB_NAME=demo # 启动服务 python app/main.py # 或: uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 ``` 访问： - API 文档：http://localhost:8000/docs - 前端页面：http://localhost:8000/static/index.html - 健康检查：http://localhost:8000/health **API 接口一览**： | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/v1/users/` | 用户列表（分页 + 多条件筛选） | | POST | `/api/v1/users/` | 创建用户 | | GET | `/api/v1/users/{id}` | 用户详情 | | PUT | `/api/v1/users/{id}` | 更新用户 | | DELETE | `/api/v1/users/{id}` | 删除用户 | | PUT | `/api/v1/users/{id}/activate` | 启用/停用用户 | --- ### 2️⃣ 启动 AI 聊天助手（snail-ai-oamr） ```bash cd snail-ai-oamr/backend # 安装依赖 pip install -r requirements.txt # 配置环境变量 export DASHSCOPE_API_KEY=your_api_key_here # 确保 Milvus 已启动（默认 localhost:19530） # 启动服务 python main.py # 或: uvicorn main:app --reload --host 0.0.0.0 --port 8100 ``` 访问：http://localhost:8100 **接口**： | 方法 | 路径 | 说明 | |------|------|------| | GET | `/` | 聊天页面 | | POST | `/chat` | SSE 流式聊天（`body: {"message": "你好"}`） | --- ## 🧠 核心亮点 ### LangGraph 工作流 - 问题先经过**分类 Agent**（5 类），再路由到对应的**专业 Agent** - `MemorySaver` 实现对话记忆隔离（thread_id 隔离会话） - 支持扩展工具调用（业务操作 Agent 示例） ### 混合检索（RAG） - **向量检索**：Milvus 语义相似度搜索 - **BM25 检索**：jieba 分词 + 关键词匹配 - **混合策略**：加权合并，互补语义和精确匹配的各自优势 ### 优雅的工程实践 - 统一异常处理（自定义业务异常、参数验证异常、数据库异常） - 统一响应格式（`code + message + data`） - Pydantic 双层验证（请求 + 响应） - 完整的日志体系 --- ## 📚 文档索引 | 文档 | 路径 | |------|------| | 第1天：基础概念映射 | `docs/第1天，基础概念映射.md` | | 第2天：FastAPI | `docs/第2天，FastAPI.md` | | 第3天：SQLAlchemy | `docs/第3天，SQLAlchemy.md` | | 第4天：异步编程 | `docs/第4天，异步编程.md` | | 第5天：异常与日志 | `docs/第5天，异常与日志.md` | | 第6天：项目实战—用户管理 | `docs/第6天，项目实战—用户管理.md` | | 第7天：AI应用—基础概念 | `docs/第7天，AI应用—基础概念.md` | | 第8天：AI应用—Milvus向量数据库 | `docs/第8天，AI应用—Milvus向量数据库.md` | | Java转Python学习（第1天） | `docs/Java转Python学习文档/第1天，基础概念映射.md` | | Java转Python学习（第2天） | `docs/Java转Python学习文档/第2天，FastAPI.md` | | RAG检索问题分析 | `snail-ai-oamr/backend/rag/RAG检索问题.md` | --- ## 🤝 贡献 欢迎提交 Issue 和 Pull Request！ --- ## 📄 许可证 MIT License --- ## 📬 联系方式 - Gitee: https://gitee.com/WilliamWangmy/snail-ai - 问题反馈: 请在 Gitee Issues 中提交