# KGEX

**Repository Path**: NoPua/kgex

## Basic Information

- **Project Name**: KGEX
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KGEX

面向地学知识增强问答与 GraphRAG 研究的科研型工程项目。

KGEX 以“证据优先、可追溯、可复现”为核心：大语言模型用于理解问题、生成计划和组织答案；地学事实则优先来自文档、知识图谱、结构化/空间数据、多模态资料和可复算工具。系统不会把模型生成的看似合理文本当作无来源的事实。

> 当前处于架构与基础工程搭建阶段。现有可运行能力为 FastAPI 健康检查；文档检索、知识图谱、证据验证、Planner、评测与多模态能力将按研究路线逐步实现。

## 研究目标

项目聚焦地学领域中需要实体、关系、时空条件和来源证据支撑的问题，例如：

- 某盆地或层段的岩性、沉积环境与储层物性关系；
- 井、层段、深度范围和测井指标约束下的筛选与统计；
- 基于文献、图谱和数据库的多跳因果解释；
- 岩芯照片、薄片、测井曲线、地震剖面和地质图等多模态资料检索；
- 可回溯到原始段落、三元组、查询结果或图件的引用式回答。

## 系统链路

```text
用户问题
  → 查询理解：意图、实体、约束与子问题
  → Planner：模板优先、LLM 兜底、校验后执行
  → 检索路由：文档 / 图谱 / SQL / GIS / 多模态
  → Candidate：多源结果标准化
  → Evidence：对齐、去重、重排、冲突与充分性验证
  → 受控推理与工具调用
  → Claim：结论—证据映射
  → Answer：结论、依据、适用条件、引用与置信度
```

关键原则：

- LLM 不直接决定事实；关键结论必须由 `Evidence` 支持。
- 图谱用于定位实体与关系链，文档和数据用于提供原始证据、数值和限定条件。
- SQL、Cypher、GIS 与数值工具均应受白名单、参数校验、超时和只读权限约束。
- 证据不足或互相冲突时，系统应说明不确定性，而非补全答案。

完整设计见[架构设计](架构设计.md)。

## 项目结构

```text
src/kgex/          可复用核心包：core、application、knowledge、qa、api、evaluation
configs/           可版本化配置：默认值、组件与实验覆盖
docker/             本地 Docker 依赖：Unstructured 文档解析 API
data/              本地数据工作区：原始、处理中、处理后数据与小样例
notebooks/         研究探索、实验验证和误差分析
experiments/       实验卡、假设、配置关联与结果登记
benchmarks/        固定评测题集、协议、基线与人工评审规范
artifacts/         本地模型、索引、缓存、日志和预测等运行产物
reports/           经筛选的论文图、汇总表和阶段报告
scripts/           调用核心包的薄 CLI
tests/             unit / contract / integration / e2e 测试
docs/              架构、数据规范、接口与决策记录
```

`src/kgex` 的职责按业务链路拆分：

| 模块 | 职责 |
| --- | --- |
| `core` | 稳定模型、Port、配置、日志、异常和其他无业务基础能力 |
| `application` | 工作流编排、重试/降级和运行时具体实现装配 |
| `knowledge` | 文档/图谱/数据入库、检索、Candidate 与 Evidence 构建 |
| `qa` | 查询理解、Planner、受控推理和引用式答案 |
| `evaluation` | 指标、批量评测、统计与误差分析 |
| `api` | FastAPI HTTP 边界、生命周期与错误映射 |

更完整的目录边界、依赖方向和实验约定见[项目目录说明](docs/项目目录说明.md)。

## 当前运行方式

当前尚未提交 `pyproject.toml`、锁文件或统一依赖清单，因此暂不存在可复制的标准安装命令。准备好包含 FastAPI 和 Uvicorn 的 Python 环境后，可启动现有开发入口：

```bash
uvicorn kgex.api.app:app --app-dir src --reload
```

或使用兼容入口：

```bash
uvicorn main:app --reload
```

服务启动后访问：

```text
GET /health
```

预期返回：

```json
{"status": "ok"}
```

首次建立依赖管理时，应补充 `pyproject.toml`、锁文件、开发依赖和本节的安装/测试命令；不要把本地环境说明当作项目可复现环境。

## 科研工作流

一次可追溯实验使用同一个 `experiment_id` 串联配置、分析和产物：

```text
configs/experiments/<experiment_id>.yaml
experiments/registry/<experiment_id>.yaml
notebooks/.../<experiment_id>_analysis.ipynb
artifacts/<experiment_id>/
reports/figures/<experiment_id>_*.png
```

每次实验至少记录：研究问题、假设、基线、唯一变量、指标、数据版本/哈希、数据切分、样本数、随机种子、代码版本、环境版本和局限性。

Notebook 是研究界面，不是核心实现。可复用代码下沉到 `src/kgex`，批量流程放入 `scripts`，稳定断言进入 `tests`。详细要求见[notebooks 说明](notebooks/README.md)和[experiments 说明](experiments/README.md)。

## 数据与安全

- `data/external`、`data/raw` 视为只读；处理结果创建新的版本。
- 大型论文、井数据、图件、索引和数据库备份不提交 Git；仅提交脱敏样例、Schema、manifest、哈希和获取说明。
- 密钥、Token、连接串和内网地址仅通过环境变量或密钥服务注入。
- 外部文档、网页和模型输出均是不可信输入，不能影响系统指令或扩大工具权限。

详情见[data 说明](data/README.md)。

## 本地基础设施

本地开发仅使用 [Unstructured 文档解析 API](docker/README.md)。镜像版本和 API Key
位于未提交的 `docker/.env` 中；不要将该 Compose 配置直接用于生产。

## 开发与测试

AI 和开发者应遵循[AI 编码规则](AGENTS.md)，其中定义了代码风格、模块边界、类型/异常/日志规范、LLM 工具约束和交付标准。

测试分为：

- `tests/unit`：不连接外部服务的快速测试；
- `tests/contract`：跨模块 Schema 与适配器输入输出测试；
- `tests/integration`：向量库、图数据库和关系数据库等真实服务测试；
- `tests/e2e`：小型固定数据上的端到端证据链测试。

目前项目尚未提交测试运行配置。添加任何可执行能力时，应同时添加最小充分测试，并在依赖清单建立后补充统一的 lint、类型检查和测试命令。

## 实施路线

1. **可验证问答基线**：文档库、地学本体、知识图谱、证据融合、验证和引用式回答。
2. **结构化数据与工具分析**：PostgreSQL/PostGIS、测井与生产数据、Planner 和受控计算。
3. **多模态扩展**：岩芯、薄片、曲线、剖面和遥感资料的联合检索与解释。
4. **工程固化**：将验证有效的实验逻辑沉淀为核心库、CLI 和自动化测试，再依据实际性能决定是否拆分服务。

## 相关文档

- [总体架构设计](架构设计.md)
- [项目目录设计](docs/项目目录说明.md)
- [AI 编码规则](AGENTS.md)
- [配置说明](configs/README.md)
- [评测资产说明](benchmarks/README.md)
- [测试说明](tests/README.md)