# dpdk_agent_mvp

**Repository Path**: kianzhang_dev/dpdk_agent_mvp

## Basic Information

- **Project Name**: dpdk_agent_mvp
- **Description**: 基于 DPDK CoreDump、运行日志与领域知识库构建 AI 故障诊断系统，设计轻量级 Agentic RAG Workflow，实现“异常解析 → 特征提取 → 案例检索 → 诊断生成 → 结构化输出”的完整闭环。

项目采用 LangGraph 构建多阶段 Agent 工作流，将复杂故障分析拆分为特征提取、检索调度、结果聚合等多个节点，提升复杂场景下的问题定位能力与可解释性。

- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: lastBranch
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-01
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DPDK Diagnosis Python AI Service

本项目是 DPDK 故障诊断系统中的 Python AI 诊断服务，负责对 CoreDump 和日志内容进行解析、检索、推理并产出结构化诊断结果。

## 1. 服务定位

- 输入：`coredump` 或 `log` 任务（通过 HTTP API）
- 核心流程：`parse -> retrieve (embedding + BM25 + rerank) -> report`
- 运行模式（engineering）：规则化/工程模式（稳定、可解释）
- 运行模式（ai）：启用大模型增强（输出 AI 元信息）
- 输出：统一 JSON 报告（含置信度、建议、证据链、可选 WebSearch 引用）

## 2. 当前能力

- CoreDump 解析（`gdb`）并提取调用栈
- 日志诊断（风险文本上下文分析）
- RAG 检索链路（embedding + BM25 + 重排）
- AI/工程双模式切换（`mode=engineering|ai`）
- AI 元信息透传：`ai_model`、`ai_latency_ms`
- 低置信度自动增强：AI 模式且 `confidence < 0.65` 时触发 WebSearch
- WebSearch 回传字段：`web_search_used`、`web_search_error`、`web_references`

## 3. 目录结构（Python 服务）

```text
dpdk_ageny_mvp/
├── api/
│   └── server.py                    # HTTP API 入口
├── src/
│   ├── config/
│   │   └── llm_config.py            # LLM 配置与客户端
│   ├── diagnosis/
│   │   ├── agent.py                 # 诊断总入口（mode/llm 开关）
│   │   ├── task_manager.py          # 任务管理与结果模型
│   │   ├── report_generator.py      # 报告生成（含低置信度 web_search）
│   │   └── contracts.py             # 结构化报告契约
│   ├── rag/
│   │   ├── ingester/                # 文档切片与索引
│   │   └── retriever/               # 检索逻辑
│   └── tools/
│       ├── gdb_core_parser.py       # core 解析
│       └── web_search.py            # web 搜索工具
├── cases/
│   └── cases.json
├── pyproject.toml
└── uv.lock
```

## 4. 环境要求

- Python `>= 3.11`
- Linux（建议）
- `gdb`（分析 coredump 必需）

安装示例：

```bash
sudo apt-get update
sudo apt-get install -y gdb
```

## 5. 初始化与启动

```bash
# 1) 进入目录
cd /home/damsu/code/new_dpdk_proj/dpdk_ageny_mvp

# 2) 安装 uv（若未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3) 安装依赖（基于 uv.lock）
uv sync

# 4) 创建环境变量文件（项目内目前无 .env.example）
cat > .env <<'ENV'
DASHSCOPE_API_KEY=your_api_key
DASHSCOPE_MODEL=MiniMax/MiniMax-M2.7
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# 可选通用变量（按需）
# LLM_API_KEY=
# LLM_MODEL=
# LLM_BASE_URL=

# 检索/Embedding（按需）
# SILICONFLOW_API_KEY=
# RERANK_EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
ENV

# 5) 启动 API 服务（默认 8000）
uv run python api/server.py
```

健康检查：

```bash
curl http://localhost:8000/api/health
```

## 6. 核心 API

### 6.1 同步诊断：`POST /api/task/direct`

CoreDump 诊断示例：

```bash
curl -X POST http://localhost:8000/api/task/direct \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "coredump",
    "payload": {
      "core_path": "/tmp/coredumps/core.demo.12345",
      "mode": "ai"
    },
    "timeout_seconds": 60
  }'
```

日志诊断示例：

```bash
curl -X POST http://localhost:8000/api/task/direct \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "log",
    "payload": {
      "log_content": "[ERROR] segmentation fault ...",
      "mode": "engineering"
    }
  }'
```

### 6.2 异步任务：`POST /api/task/submit` + `GET /api/task/status/{task_id}`

```bash
curl -X POST http://localhost:8000/api/task/submit \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "coredump",
    "payload": {
      "core_path": "/tmp/coredumps/core.demo.12345",
      "mode": "engineering"
    }
  }'
```

```bash
curl http://localhost:8000/api/task/status/<task_id>
```

### 6.3 兼容接口：`POST /api/analyze`

```bash
curl -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"core_path":"/tmp/coredumps/core.demo.12345"}'
```

## 7. 关键返回字段（与前端联动）

诊断结果 `result` 常见字段：

- `summary`：诊断摘要
- `root_cause`：根因
- `confidence`：置信度
- `matched_cases`：匹配案例
- `suggestions`：修复建议
- `call_stack`：调用栈（coredump 时）
- `mode`：`engineering` / `ai`
- `ai_used`：是否启用 AI 分支
- `ai_model`：模型名
- `ai_latency_ms`：模型耗时（毫秒）
- `web_search_used`：是否触发 WebSearch
- `web_search_error`：WebSearch 错误（若有）
- `web_references`：外部参考链接/来源

## 8. 与 Go/前端的关系

本仓库是 Python AI 服务；完整系统通常为：

- Go Watcher：监控 core/log、任务调度、通知
- Python Service（本项目）：执行诊断推理
- Next 前端：展示调用栈、诊断报告、AI 元信息

## 9. 常见问题

### Q1：AI 模式和工程模式看起来没区别？

确认请求中传了 `payload.mode="ai"`，并检查返回里 `ai_used=true`、`ai_model` 非空。

### Q2：为什么没有触发 WebSearch？

仅在 AI 模式且低置信度（`confidence < 0.65`）时触发。

### Q3：core 文件有效但分析失败？

优先检查：

- `gdb` 是否安装
- `core_path` 是否真实可读
- core 是否完整（非空/未损坏）

### Q4：`core.xxx`、`core-xxx`、`*.core` 有区别吗？

Python 服务按 `core_path` 读取，不依赖后缀名；但上层前端上传和 watcher 常有命名匹配规则，建议统一命名约定。

## 10. 测试与调试

```bash
cd /home/damsu/code/new_dpdk_proj/dpdk_ageny_mvp

# 报告生成模块单测
uv run python -m unittest src/diagnosis/test_report_generator.py

# 解析工具测试
uv run python -m unittest src/tools/test_parse_crash_log.py
uv run python -m unittest src/tools/test_rerank.py

# API 冒烟
uv run python test_api.py
```