fahmidme/incident-triage-api

# 事件分诊 API [](https://www.python.org/) [](https://fastapi.tiangolo.com/) [](https://www.sqlite.org/fts5.html) [](https://docs.pytest.org/) [](https://platform.openai.com/docs/api-reference/responses) 一个小型、本地优先的事件工单搜索和分诊 API。它加载模拟事件，使用 SQLite FTS5 进行搜索，并利用基于检索增强的 LLM 助手来建议后续步骤并起草简短的客户回复。 此代码库专为公开的 GitHub 提交而设计。它仅包含模拟数据，不包含任何私人公司数据、个人身份信息（PII）或机密信息。 ## 核心亮点 - 300 张使用固定随机种子生成的模拟事件工单。 - 幂等的摄入操作，并提供 `ingested`、`updated` 和 `skipped` 的计数。 - SQLite FTS5 搜索，支持按环境、服务、严重程度和标签进行过滤。 - 基于事实的 `/assist` 流程，在调用 LLM 之前会先检索相关事件。 - 结构化的 OpenAI 响应解析，以及服务器端的引用验证。 - 日志中的 Correlation ID，以及用于追踪助手步骤的 trace endpoint。 - 针对摄入行为、搜索过滤器、助手防护机制和 API 冒烟测试流程的测试用例。 ## 架构 ``` data/incidents.json | v POST /ingest ---> SQLite incidents table + FTS5 index | v GET /search ------------------------------+ | POST /assist ---> same search path --------+--> retrieved incidents --> OpenAI Responses API | | +--> trace steps: tool input, hits, selected IDs <--------+ ``` LLM 并不被视为唯一事实来源。它仅接收检索到的事件，并且 API 会拒绝引用了该检索集合之外事件 ID 的响应。 ## 快速开始 安装依赖项： ``` uv sync --extra dev ``` 创建本地环境配置： ``` cp .env.example .env ``` 如需使用 `/assist`，请在 `.env` 中添加 OpenAI 密钥： ``` LLM_API_KEY=your_api_key_here ``` 生成可复现的数据集： ``` uv run python scripts/generate_data.py ``` 启动 API： ``` uv run uvicorn incident_triage.app:app --reload --port 8000 ``` 如果端口 `8000` 已被占用，请使用其他端口： ``` uv run uvicorn incident_triage.app:app --reload --port 8010 ``` ## API 健康检查： ``` curl http://localhost:8000/health ``` 摄入事件： ``` curl -X POST http://localhost:8000/ingest ``` 连续运行两次摄入操作以验证幂等性。第二次响应应将所有记录报告为 `skipped`。 搜索： ``` curl "http://localhost:8000/search?q=login%20failures&environment=prod&limit=5" ``` 使用标签过滤器搜索： ``` curl "http://localhost:8000/search?q=queue%20latency&tags=payroll&tags=batch" ``` 获取事件详情： ``` curl http://localhost:8000/incidents/INC-0001 ``` 向助手提问： ``` curl -X POST http://localhost:8000/assist \ -H "Content-Type: application/json" \ -H "X-Correlation-ID: demo-123" \ -d '{ "question": "Customers report login failures after token refresh in prod", "environment": "prod" }' ``` 检查助手追踪记录： ``` curl http://localhost:8000/debug/trace/demo-123 ``` ## 配置说明 | 变量 | 默认值 | 用途 | |---|---:|---| | `PORT` | `8000` | 示例中使用的本地服务器端口 | | `DATABASE_URL` | `data/incidents.db` | SQLite 数据库路径 | | `DATA_PATH` | `data/incidents.json` | 由 `/ingest` 加载的事件 JSON 文件 | | `LLM_PROVIDER` | `openai` | 运行时的 LLM 提供商 | | `LLM_API_KEY` | 空 | `/assist` 所必需 | | `LLM_MODEL` | `gpt-5.5` | `/assist` 使用的 OpenAI 模型 | | `LLM_TIMEOUT_SECONDS` | `20` | LLM 请求超时时间 | ## 测试 ``` uv run pytest ``` 当前的测试覆盖重点： - 幂等摄入操作与源数据重复检测。 - 查询/过滤行为及返回数量限制。 - 助手零命中行为、LLM 失败处理及引用防护机制。 - 针对摄入、搜索、详情、助手及追踪查询的 API 冒烟测试流程。 ## 安全说明 - `.env`、本地数据库、字节码、日志以及类似密钥的文件均已被 git 忽略。 - SQL 语句使用参数绑定；FTS 查询在传递给 SQLite 之前会先进行分词处理。 - Correlation ID 在回显到响应头之前会进行约束限制。 - `/assist` 会验证所引用的事件 ID 是否来自于检索到的记录。 - 身份验证（Auth）有意作为一项待跟进的说明事项留在了 `TRADEOFFS.md` 中。 ## 设计权衡 SQLite FTS5 被选为 v1 版本的搜索后端，因为它是确定性的、本地化的、易于检查，并且对于 200-500 条工单的数据集来说已经足够。向量嵌入（Embeddings）作为一种更大规模的混合检索升级方案，已在 `TRADEOFFS.md` 中作了记录。 ## 文档 - `PROMPTS.md` 记录了经过清理的 AI/工具使用历程。 - `AI-NOTES.md` 记录了 Codex 的实现说明与局限性。 - `TRADEOFFS.md` 说明了已完成的工作、未完成的工作以及后续计划。

标签：API, AV绕过, FastAPI, SQLite, 全文检索, 安全规则引擎, 工单系统, 幻觉缓解, 网络研究, 运维管理, 逆向工具