# bidding_agent

**Repository Path**: xl2hui/bidding_agent

## Basic Information

- **Project Name**: bidding_agent
- **Description**: 评标智能体系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-13
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能招投标管理系统

基于 Django 的招投标评审辅助系统。项目围绕“招标文件解析、投标文件证据抽取、指标匹配、AI 评分评价、评标总结生成”构建，后端采用分层 Service 架构，业务数据主要通过 MySQL 原始 SQL 管理，并结合 Neo4j 知识图谱、Chroma 向量检索和大模型能力实现 GraphRAG 工作流。

## 当前功能

- **项目与投标人管理**：维护项目、投标人、招标/投标文件关系。
- **PDF 文档解析**：上传招标文件或投标文件后保存到 `media/uploads/`，解析为 `bidding_chunks` 逻辑片段。
- **招标文件专用解析**：`TenderTextSpliter` 优先使用文本结构、目录、标题和表格规则解析招标文件；不适合文本解析时回退到通用视觉解析。
- **通用文档解析**：`Spliter` 使用 `pymupdf4llm` 提取 Markdown，并在含图页面调用智谱视觉模型辅助分割。
- **GraphRAG 指标匹配**：将招标文件 chunk 与 Neo4j 中的 `Indicator -> Rule -> VerificationObject` 图谱上下文进行混合匹配，生成项目指标。
- **GraphRAG 验证物抽取**：将投标文件 chunk 与 Neo4j `VerificationObject` 匹配，生成候选证据项，并保留 chunk 溯源关系。
- **向量检索**：上传解析后可将 chunk 通过智谱 `embedding-2` 写入 Chroma，用于关键词 + 向量混合检索。
- **AI 评分评价**：对“已确认指标 × 已确认验证物”执行匹配和 DeepSeek 评价，写入 `indicator_match_result`。
- **评标总结与导出**：汇总评分、报价和风险点，生成 `review_result`，支持导出 DOCX 评标报告。
- **对话助手**：基于 LangGraph 的 Chat Agent，支持上传、项目查询、流程建议和权限守卫。
- **双角色权限**：`admin` 负责项目、指标、文件、评标总结；`reviewer` 负责证据审核和评分评价。
- **审计追踪**：关键人工操作写入 `human_review_record`，保存 before/after 快照。

## 技术栈

| 层面 | 实现 |
|------|------|
| Web 框架 | Django 6.0 |
| 业务数据库 | MySQL + PyMySQL 原始 SQL |
| Django 系统库 | SQLite，仅用于 Django session/admin 等系统表 |
| 图数据库 | Neo4j，存储指标、规则、验证物、章节关系 |
| 向量数据库 | Chroma 持久化目录 `vector_db/` |
| 文本大模型 | DeepSeek V4 Flash/Pro，OpenAI 兼容客户端 |
| 视觉与 Embedding | 智谱 GLM-4.6V、`embedding-2` |
| PDF 处理 | PyMuPDF、pymupdf4llm |
| 对话编排 | LangGraph |
| 前端 | Django 模板 + 原生 JavaScript |

## 架构概览

```
bidding_app/
├── views/views.py             # 页面渲染、鉴权检查、API 入口
├── services/
│   ├── document_service.py    # 文件上传、保存、删除、分角色解析编排
│   ├── tender_text_spliter.py # 招标文件文本优先解析
│   ├── spliter.py             # 通用 PDF/视觉解析
│   ├── rag_service.py         # GraphRAG 核心：指标、证据、评分、总结
│   ├── vector_service.py      # Chroma 向量写入与检索
│   ├── neo4j_client.py        # Neo4j 图谱查询
│   ├── ai_client.py           # DeepSeek、智谱视觉、智谱 embedding 封装
│   ├── chat_agent_service.py  # LangGraph 对话代理
│   ├── auth_service.py        # 自定义 session 用户体系
│   ├── audit_service.py       # 人工审核/关键操作审计
│   ├── db_client.py           # MySQL 原始 SQL 客户端
│   └── pdf_processor.py       # PDF 验证、文本提取、页面转图片
├── middleware.py              # LoginRequiredMiddleware
└── models.py                  # 业务数据不使用 Django ORM
```

## 数据存储

### MySQL

业务主库，默认库名 `ai_bidding`。项目不使用 Django ORM 管理业务表，服务层通过原始 SQL 读写，并在部分流程中执行 `CREATE TABLE IF NOT EXISTS` 或补列操作。

主要业务表包括：

- `system_user`：登录用户，包含 `admin` 和 `reviewer`。
- `project`：评标项目，含 `score_scale`。
- `bidder`：投标人，关联项目和投标文件。
- `bidding_files`：上传文件。
- `bidding_chunks`：PDF 解析后的逻辑片段，含 `type`、`summary`、`detail`、页码。
- `project_indicator`：从招标文件匹配出的项目评审指标。
- `project_indicator_chunk`：项目指标与来源 chunk 的多对多溯源。
- `evidence_item`：从投标文件抽取出的验证物/证据项。
- `evidence_item_chunk`：证据项与来源 chunk 的多对多溯源。
- `indicator_match_result`：指标评分评价结果。
- `review_result`：评标总结和推荐结果。
- `human_review_record`：人工操作审计记录。

### Neo4j

存储评审知识图谱，当前代码实际使用的核心节点和关系是：

- `Indicator`：评审指标。
- `Rule`：评审规则。
- `VerificationObject`：验证物类型。
- `Chapter`：章节。
- `INDICATOR_RULE`：指标到规则。
- `RULE_VERIFICATION`：规则到验证物。
- `INDICATOR_VERIFICATION`：指标到验证物。
- `INDICATOR_CHAPTER`：指标到章节。

### Chroma

用于 chunk 级语义检索。`GraphRAGService.sync_file_chunks_to_vectors()` 会将 `bidding_chunks` 的文本通过智谱 embedding 写入 Chroma collection `bidding_chunks`。

注意：当前 `requirements.txt` 未固定 `chromadb`，如需启用向量检索，需要额外安装：

```bash
pip install chromadb
```

## 核心流程

### 文件上传解析

```text
POST /api/upload/
  -> DocumentService.upload_and_split()
  -> 保存文件到 media/uploads/
  -> 写入 bidding_files
  -> 按 file_role 选择解析器
     - tender: TenderTextSpliter 优先，失败后 Spliter 回退
     - bid: Spliter 通用解析
  -> 写入 bidding_chunks
  -> 同步 chunk 向量到 Chroma
  -> tender 自动执行项目指标匹配
  -> bid 自动执行验证物抽取
```

### 招标文件到项目指标

```text
bidding_chunks
  -> match_project_indicators()
  -> Neo4j 读取 Indicator/Rule/VerificationObject 上下文
  -> 关键词 + 图上下文 + 字符串相似度 + 可选向量相似度
  -> 生成 project_indicator
  -> 通过 project_indicator_chunk 保留来源片段
  -> 管理员人工确认
```

### 投标文件到验证物

```text
bidding_chunks
  -> extract_evidence_items()
  -> Neo4j 读取 VerificationObject
  -> chunk 类型/detail 与验证物名称/描述匹配
  -> 生成 evidence_item
  -> 通过 evidence_item_chunk 保留来源片段
  -> 评审员或管理员人工确认
```

### 指标评价

```text
已确认 project_indicator × 已确认 evidence_item
  -> run_indicator_evaluation()
  -> 图谱规则 + 验证物要求 + 候选证据
  -> DeepSeek 生成评分、结论、理由、风险点
  -> 写入 indicator_match_result
  -> 人工审核或修正
```

### 评标总结

```text
indicator_match_result + 报价信息
  -> run_review_summary()
  -> 综合评分法/最低价法排序
  -> DeepSeek 生成总结、风险点、建议
  -> 写入 review_result
  -> 导出 DOCX
```

## GraphRAG 实现状态

当前项目已经实现了“工程化 GraphRAG 流程”，但不是纯粹的论文式“图数据库检索 + 文本生成回答”单一路径。

已实现内容：

- Neo4j 图谱作为指标、规则、验证物的结构化知识源。
- 招标文件 chunk 到图谱 Indicator 的匹配。
- 投标文件 chunk 到图谱 VerificationObject 的匹配。
- 图谱规则和验证物关系参与指标评价提示词构建。
- MySQL 保存匹配结果、人工确认结果和溯源关系。
- Chroma 向量库参与 chunk 语义检索和候选召回。
- DeepSeek 用于指标评价、总结生成和部分 LLM 重排序/补全。

## API 概览

### 页面

| 路径 | 说明 |
|------|------|
| `/` | 仪表盘 |
| `/login/` | 登录页 |
| `/projects/` | 项目管理 |
| `/upload/` | 文件上传 |
| `/indicators/` | 指标管理 |
| `/evidence/` | 证据审核 |
| `/evaluations/` | 指标评价 |
| `/review_summary/` | 评标总结 |
| `/chat/` | 对话助手 |
| `/users/` | 用户管理 |

### 主要接口

| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/api/auth/login/` | 登录 |
| GET | `/api/auth/logout/` | 退出 |
| GET/POST | `/api/auth/profile/` | 个人资料 |
| GET/POST | `/api/users/` | 用户管理 |
| GET/POST | `/api/projects/` | 项目列表/创建 |
| GET/POST | `/api/bidders/` | 投标人列表/创建 |
| POST | `/api/upload/` | 上传并解析 PDF |
| POST | `/api/analyze_and_upload/` | 先识别招投标文件再上传解析 |
| POST | `/api/save_file/` | 仅保存文件 |
| GET | `/api/files/` | 文件列表 |
| GET | `/api/fragments/` | chunk/片段列表 |
| GET | `/api/download/<file_id>/` | 下载 PDF |
| GET/POST | `/api/project_indicator/` | 项目指标 |
| POST | `/api/project_indicator/run_rag/` | 重跑招标文件指标匹配 |
| POST | `/api/project_indicator/approve/` | 指标人工确认 |
| GET | `/api/graph/indicators/` | 查询 Neo4j 图谱指标 |
| GET | `/api/evidence/` | 证据项列表 |
| POST | `/api/rag/extract_evidence/` | 重跑投标文件验证物抽取 |
| GET | `/api/indicator_evaluations/` | 指标评价列表 |
| POST | `/api/indicator_evaluations/run_rag/` | 生成指标评分评价 |
| GET | `/api/review_results/` | 评标总结列表 |
| POST | `/api/review_results/run_summary/` | 生成评标总结 |
| GET | `/api/review_results/export/` | 导出评标报告 DOCX |
| POST | `/api/chat/` | 对话助手 |
| GET | `/api/health/` | 健康检查 |

## 环境变量

| 变量 | 用途 | 默认值 |
|------|------|------|
| `DEEPSEEK_API_KEY` | DeepSeek 文本模型 API 密钥 | 无 |
| `ZHIPUAI_API_KEY` | 智谱视觉模型和 embedding API 密钥 | 无 |
| `DB_HOST` | MySQL 主机 | `localhost` |
| `DB_USER` | MySQL 用户 | `root` |
| `DB_PASSWORD` | MySQL 密码 | `123456` |
| `DB_NAME` | MySQL 数据库 | `ai_bidding` |
| `NEO4J_URI` | Neo4j URI | `bolt://localhost:7687` |
| `NEO4J_USER` | Neo4j 用户 | `neo4j` |
| `NEO4J_PASSWORD` | Neo4j 密码 | 无 |
| `BIDDING_DEFAULT_USERNAME` | 初始管理员用户名 | `admin` |
| `BIDDING_DEFAULT_PASSWORD` | 初始管理员密码 | `admin123456` |
| `BIDDING_DEFAULT_DISPLAY_NAME` | 初始管理员显示名 | `管理员` |
| `APP_LOG_LEVEL` | 应用日志等级 | 代码默认 |

## 快速开始

```bash
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
pip install chromadb

set DEEPSEEK_API_KEY=sk-xxx
set ZHIPUAI_API_KEY=xxx
set NEO4J_PASSWORD=your-password

python manage.py runserver 0.0.0.0:8000
```

首次登录默认管理员：

- 用户名：`admin`
- 密码：`admin123456`

## 测试

```bash
python manage.py test
```

当前测试覆盖了权限、DOCX 导出、Chat 权限、视觉响应解析、片段清洗、指标评价、招标文本解析等核心逻辑。

## 开发注意事项

1. 业务表不使用 Django ORM，不要为业务数据新增 Django migration。
2. `DBClient` 每次操作新建 MySQL 连接，没有连接池。
3. 登录态使用 signed cookie session，自定义 `LoginRequiredMiddleware` 对页面和 API 做统一拦截。
4. 多数业务 API 使用 `@csrf_exempt`，权限主要依赖 session 用户角色判断。
5. `rag_service.py` 是核心业务文件，包含指标匹配、证据抽取、评分、总结、导出和表结构补齐逻辑。
6. `file_role=tender` 表示招标文件，`file_role=bid` 表示投标文件；投标文件上传必须带 `bidder_id`。
7. 解析结果以 `bidding_chunks` 为中心，后续指标、证据、评分都通过 chunk 溯源。