sarveshkb21/aiops-assistant

# AIOps 事件响应助手 这是一个基于 RAG 的聊天机器人，旨在帮助 IT 值班工程师在事件发生时，利用 LangChain、ChromaDB、Gemini 和 Streamlit 即时查找修复步骤。 它采用了一个轻量级的 **multi-agent router**：每个查询首先会被分类到特定的领域（kubernetes、database、infrastructure、network、security），然后由专门处理该领域的 agent 负责仅从该领域的 runbook 中检索信息并作出回答。 ## 技术栈 | 组件 | 工具 | |-----------------|-----------------------------| | LLM | Google Gemini 2.5 Flash | | Embeddings | Google gemini-embedding-2 | | Framework | LangChain 1.x | | Vector Store | ChromaDB (本地) | | UI | Streamlit | | Language | Python 3.10+ | ## 工作原理（Multi-Agent 路由） ``` flowchart TD Q["🧑‍💻 Engineer query"] --> R["🧭 Router
(router.classify_query · Gemini)"] R -->|kubernetes| K["☸️ Kubernetes Agent"] R -->|database| D["🗄️ Database Agent"] R -->|infrastructure| I["🖥️ Infrastructure Agent"] R -->|network| N["🌐 Network Agent"] R -->|security| S["🔒 Security Agent"] R -->|general / fallback| G["🧭 General Agent"] K & D & I & N & S & G --> C[("🗃️ ChromaDB
filtered by domain")] C --> A["💬 Answer + agent badge + sources"] ``` 每个专门处理特定领域的 agent 由 `get_agent_chain()` 构建，并且仅从其领域的 runbook 中进行检索。这些 agent 在 `agents.py` 中被定义为注册表（`ROUTER` + `AGENTS`），并由 `app.py` 统一驱动。 每个查询都会经过三个步骤： 1. **Route** — `router.classify_query()` 会发起一次 Gemini 调用，将查询分类到一个具体的领域：`kubernetes`、`database`、`infrastructure`、`network`、`security` 或 `general`。 2. **Retrieve（限定领域范围）** — `rag_chain.get_agent_chain(domain)` 会构建一个 RetrievalQA 链，其 ChromaDB retriever 会通过 `domain` 元数据进行过滤，因此专门处理该领域的 agent 只能看到属于自己领域的 runbook。`general` 则不应用任何过滤，会搜索所有内容。 3. **Answer + badge** — 应用会在响应上方显示一个带有颜色的 agent 徽章（☸️ Kubernetes、🗄️ Database、🖥️ Infrastructure、🌐 Network、🔒 Security、🧭 General），并在下方列出引用的源 runbook。 **路由错误的兜底机制：** 如果路由到的领域没有匹配到任何 runbook，应用会自动进行无过滤重试（`general`），这样错误的路由就不会导致正确的 runbook 被隐藏。请注意，这意味着一个经过路由的查询最多可能会发起 **两次** Gemini 调用（路由 + 回答），如果触发了兜底机制则是三次——请合理控制免费额度的使用频率。 这些领域与 `data/runbooks/` 下的子文件夹是一一对应的。`domain` 元数据由 `ingest.py` 写入（根据每个文件所在的子文件夹推导得出），并由 retriever 过滤器读取——因此，若要添加一个新领域，只需新建一个子文件夹并重新导入数据即可（同时还要将其添加到 `router.py` 中的 `DOMAINS` 里）。 ## 设置说明 (Windows) ### 第 1 步：克隆或创建项目文件夹 ``` cd C:\Users\YourName\Documents mkdir aiops-assistant cd aiops-assistant ``` ### 第 2 步：创建并激活虚拟环境 ``` python -m venv venv venv\Scripts\activate ``` ### 第 3 步：安装依赖项 ``` pip install -r requirements.txt ``` ### 第 4 步：设置你的 API key - 将 `.env.example` 复制到 `.env` - 打开 `.env` 并将 `your_gemini_api_key_here` 替换为你真实的 key - 从此处获取你的 Gemini API key：https://aistudio.google.com/app/apikey ### 第 5 步：添加你的 runbook - 将你的 `.txt` 或 `.pdf` runbook 文件放置在 `data/runbooks//` 下 （每个领域一个子文件夹——子文件夹的名称即为路由的目标领域） - 系统已包含涵盖所有领域的示例 runbook，以便你快速上手 ### 第 6 步：将文档导入到 vector store ``` python ingest.py ``` ### 第 7 步：启动应用 ``` streamlit run app.py ``` 应用将会在以下地址打开：http://localhost:8501 ## 部署到 Streamlit Cloud 1. 将此项目推送到 GitHub 仓库（确保 `app.py` 位于仓库根目录）。 2. 在 [share.streamlit.io](https://share.streamlit.io) 上，创建一个指向 `app.py` 的应用。 3. 在 **Settings → Secrets** 下添加你的 key（Streamlit 会将 secrets 作为环境变量暴露出来，因此 `os.getenv("GOOGLE_API_KEY")` 是可以正常工作的）： GOOGLE_API_KEY = "your_key_here" 4. **提交 vector store。** `chroma_db/` 已在 `.gitignore` 中被忽略，因此全新部署的应用将没有任何知识库，并且每次查询都会失败并提示 *"Knowledge base not found."*。为了方便演示，最简单的修复方法是将预构建的存储库直接提交：从 `.gitignore` 中移除 `chroma_db/`，在本地运行 `python ingest.py`，然后提交 `chroma_db/`。 （备选方案：在服务器启动时运行导入程序——但这需要运行时具备 API key，并且每次冷启动都会消耗 embedding 配额。） ## 项目结构 ``` aiops-assistant/ ├── app.py # Streamlit UI (router -> agent -> badge) ├── agents.py # Agent registry: ROUTER + 6 named specialists ├── router.py # Classifies a query into a domain (Gemini) ├── rag_chain.py # RAG chain builder: get_agent_chain (domain-filtered) ├── ingest.py # Document ingestion pipeline (tags `domain`) ├── requirements.txt # Python dependencies ├── LICENSE # MIT license ├── CLAUDE.md # Guidance for Claude Code sessions ├── .env.example # API key template ├── .env # Your actual API key (do not commit) ├── .gitignore ├── data/ │ └── runbooks/ # One subfolder per domain │ ├── kubernetes/ │ │ └── runbook_oom_kubernetes.txt │ ├── database/ │ │ └── runbook_database.txt │ ├── infrastructure/ │ │ ├── runbook_disk_space.txt │ │ ├── runbook_high_cpu.txt │ │ └── runbook_service_health.txt │ ├── network/ │ │ ├── runbook_dns_failure.txt │ │ └── runbook_high_latency.txt │ └── security/ │ ├── runbook_unauthorized_access.txt │ └── runbook_ssl_cert_expiry.txt └── chroma_db/ # Auto-created by ingest.py ``` ## 测试用的示例查询 - 如何解决 Kubernetes 中的 OOMKilled pods？ - 处理 Linux 服务器 CPU 过高告警的步骤？ - 数据库连接池耗尽 - 该怎么办？ - 如何响应磁盘空间告警？ - 服务健康检查失败 - 排查步骤？ ## 添加更多 Runbook 1. 将你的 `.txt` 或 `.pdf` 文件添加到 `data/runbooks/` 2. 重建 vector store（请参阅下方的 **更新 Vector Store (ChromaDB)**） 3. 重启 Streamlit 应用 ## 更新 Vector Store (ChromaDB) 位于 `chroma_db/` 中的 vector store 是由 `ingest.py` 根据 `data/runbooks/` 中的文件构建的。每当你**添加、编辑或移除** runbook 时，都必须对其进行重建，这样应用才能获取到更改。 ### 重建数据库 (Windows / PowerShell) ``` Remove-Item -Recurse -Force .\chroma_db python ingest.py ``` ### 重建数据库 (macOS / Linux) ``` rm -rf ./chroma_db python ingest.py ``` 成功的重建过程会输出 `Loaded N document(s)` 以及 `SUCCESS: N chunks stored in ChromaDB`。请确认 `N` 与你期望的 runbook 数量是否一致。 ### 何时必须重建 - 你在 `data/runbooks/` 中添加、编辑或删除了 runbook - 你更改了 `rag_chain.py` 中的 `EMBEDDING_MODEL`（新旧 embeddings 是不兼容的——过时的 `chroma_db/` 会导致回答错误或出现维度错误） - 应用提示 `Knowledge base not found` 完成重建后，**请重启 Streamlit**（按 Ctrl+C，然后执行 `streamlit run app.py`）， 以便其重新加载缓存的链。 ## 故障排除 | 症状 | 原因 | 解决方法 | |---------|-------|-----| | `GOOGLE_API_KEY is not set` | 没有 `.env` 文件或缺少 key | 将 `.env.example` 复制到 `.env` 并粘贴你的 key | | `404 NOT_FOUND ... is not found for API version` | Gemini 模型名称已弃用 | 更新 `rag_chain.py` 中的模型名称（参见上方的模型说明） | | `429 RESOURCE_EXHAUSTED ... limit: 0` | 该模型仅限付费层级使用（例如 `gemini-2.5-pro`） | 切换到如 `gemini-2.5-flash` 的免费层级模型，或启用计费功能 | | `429 RESOURCE_EXHAUSTED ... retry in Ns` | 达到了免费层级的速率/每日限制 | 等待重试延迟结束；限制会随时间重置 | | 在 `rag_chain.py` 中更改模型在运行的应用中未生效 | Streamlit 缓存了旧的链 | 重启应用（按 Ctrl+C，重新运行）或使用 ⋮ 菜单 → 清除缓存 | | `ModuleNotFoundError: No module named 'langchain...'` | 依赖项已过时 | 重新运行 `pip install -r requirements.txt` | | 回答似乎与你的 runbook 无关，或查询时出现维度错误 | Vector store 是使用不同的 embedding 模型构建的 | 删除 `chroma_db/` 文件夹并重新运行 `python ingest.py` | | 应用中提示 `Knowledge base not found` | 从未运行过 `ingest.py` | 在启动应用之前运行 `python ingest.py` | ## 许可证 基于 [MIT License](LICENSE) 发布 — 可免费使用、修改和分发。 ## 毕业项目 - Build Fast with AI 作者：Sarvesh Bedsur 课程：Gen AI Launch Pad 2026

标签：AIOps, ChromaDB, IT运维, Kubernetes, LangChain, RAG架构, Socks5代理, Streamlit, 多智能体, 智能客服, 访问控制, 轻量级, 逆向工具