# mes-embedding

**Repository Path**: fall-for-you/mes-embedding

## Basic Information

- **Project Name**: mes-embedding
- **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-06-03
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MES Embedding

MES Embedding 是一个面向制造执行系统（MES）的代码语义索引与检索服务。它能够对 MES 项目中的 Java、JSP、配置文件等进行分块处理，生成结构化的语义向量，支持通过多种方式搜索代码符号、API 端点和方法调用关系。

## 功能特性

- **多语言分块支持**：Java 优先 javalang AST 分块（失败回退正则），长方法按重叠窗口二次分块，并支持 JSP、Spring/XML、MyBatis Mapper
- **多存储后端**：Elasticsearch（结构化 + 任务持久化）、Qdrant（向量）、ES trigram / Zoekt（关键词）、内存存储
- **语义检索**：向量 + 关键词 + 结构化多路召回，RRF 融合，调用图扩展
- **跨层关系**：基于稳定逻辑实体 ID 关联 Java→Mapper、JSP/Controller→HTTP endpoint、Mapper→表、代码/XML→配置项
- **GitLab Webhook**：支持 Webhook 触发；可选 Kafka 异步队列 + 30 秒文件去重
- **可靠增量**：任务状态机 + 指数退避重试 Worker；失败可重放
- **安全审计**：可选 API Key / GitLab Token 鉴权；检索与关键操作写入 audit JSONL
- **评测脚本**：`python -m mes_indexer.eval.run --eval-set samples/eval_set.jsonl`

## 快速开始

### 环境要求

- Python 3.10+
- Docker 和 Docker Compose（用于运行 Elasticsearch、Qdrant 等存储服务）

### 安装依赖

```bash
pip install -r requirements.txt
```

### 配置环境变量

复制 `.env.example` 为 `.env` 并根据实际情况修改：

```bash
cp .env.example .env
```

### 启动服务

使用 Docker Compose 启动依赖服务：

```bash
docker-compose up -d
```

### 启动索引服务

```bash
python -m mes_indexer.api.app
```

服务默认运行在 `http://localhost:8000`

## API 接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/webhook/gitlab` | POST | 接收 GitLab Webhook 事件 |
| `/index/tasks` | POST | 提交索引任务 |
| `/index/bootstrap` | POST | 提交异步全量索引任务（返回 202） |
| `/index/bootstrap/{job_id}` | GET | 查询全量索引任务状态 |
| `/index/tasks/{task_id}` | GET | 查询任务状态 |
| `/index/tasks/{task_id}/reconcile` | POST | 对账任务在各存储中的文档数量 |
| `/index/tasks/replay` | POST | 重放失败的任务 |
| `/search` | POST | 语义搜索 |

## 搜索示例

```bash
curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "your-repo",
    "query_text": "DemoService ping",
    "top_k": 10
  }'
```

`repo` 是必填隔离键；服务不会跨仓库返回检索结果。

全量索引会立即返回后台作业：

```bash
curl -X POST http://localhost:8000/index/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"repo":"your-repo","branch":"main","project_path":"/workspace/your-repo"}'
```

使用响应中的 `job_id` 查询进度：

```bash
curl http://localhost:8000/index/bootstrap/JOB_ID
```

## 项目结构

```
src/mes_indexer/
├── api/                # FastAPI 接口定义
├── chunking/           # 代码分块处理器
│   ├── java_chunker.py     # Java 方法分块
│   ├── jsp_chunker.py    # JSP 页面分块
│   ├── config_chunker.py # 配置文件分块
│   └── mapper_chunker.py # MyBatis Mapper 分块
├── pipeline/           # 索引流水线
│   ├── indexer.py       # 索引服务
│   └── task_state.py    # 任务状态机
├── search/             # 检索服务
│   ├── retrieval.py     # 检索实现
│   └── rrf.py          # Reciprocal Rank Fusion
├── storage/            # 存储后端
│   ├── elasticsearch_store.py
│   ├── qdrant_store.py
│   ├── zoekt_store.py
│   └── inmemory.py
├── config.py           # 配置定义
├── embedding_service.py # 向量化服务
├── id_model.py         # ID 模型
└── models.py         # 数据模型
```

## 测试

运行测试：

```bash
pytest
```

评测检索指标（需先有索引数据，`relevant_block_ids` 对应真实 block_id）：

```bash
python -m mes_indexer.eval.run --eval-set samples/eval_set.jsonl --k 10
```

## 生产相关环境变量

| 变量 | 说明 |
|------|------|
| `MES_INDEXER_AUTH_ENABLED` | 开启 API Key / Webhook Token 校验 |
| `MES_INDEXER_API_KEY` | API Bearer / X-API-Key |
| `MES_INDEXER_GITLAB_WEBHOOK_SECRET` | `X-Gitlab-Token` |
| `MES_INDEXER_KAFKA_ENABLED` | Webhook 改走 Kafka 异步消费 |
| `MES_INDEXER_STORAGE_BACKEND=elasticsearch` | 结构化索引 + ES 任务持久化 |
| `MES_INDEXER_KEYWORD_BACKEND` | `es_trigram`（默认）或 `zoekt` |
| `MES_INDEXER_BOOTSTRAP_ALLOWED_ROOTS` | 允许全量索引的绝对目录，逗号分隔；未设置时仅允许服务工作目录 |
| `MES_INDEXER_MAX_CHANGED_FILES` | 单次增量事件最多文件数，默认 1000 |
| `MES_INDEXER_MAX_FILE_BYTES` | 单个源码文件上限，默认 5 MiB |
| `MES_INDEXER_MAX_REQUEST_BYTES` | HTTP 请求体上限，默认 2 MiB |
| `MES_INDEXER_MAX_TOP_K` | 检索结果数上限，默认 100 |
| `MES_INDEXER_INCLUDE_GLOBS` | 索引文件 glob，默认 `*.java,*.jsp,*.xml,*.properties` |

## 一致性与健康检查

- 新文件版本写入所有后端成功后，才会清理旧版本。
- 写入阶段任一后端失败会回滚本次文件版本；旧版本清理失败会保留已完整写入的新版本，并由任务状态机重试清理。
- 文件删除会同时清理结构化、关键词、向量和调用图数据。
- embedding 生成和 Qdrant 写入是两个任务检查点；仅 Qdrant 写入重试时会复用已生成的向量。
- 每次提交前自动核对结构化、关键词、向量和调用图数量，也可通过 reconcile API 手工复核。
- `COMMITTED` 表示存储对账通过；解析质量独立记录在 `quality_status` 和 `quality_issues`，不会再被提交状态掩盖。
- XML 语法错误会使任务进入重试/DLQ，而不是作为空索引成功提交。
- `/health` 会检查启用的存储、embedding 和 Kafka；依赖异常时返回 HTTP 503。

## 集成测试

普通测试默认跳过外部依赖测试。启动 Elasticsearch、Qdrant 和 embedding 服务并配置环境变量后运行：

```bash
MES_RUN_INTEGRATION=1 \
MES_INDEXER_STORAGE_BACKEND=elasticsearch \
pytest -m integration
```

## 许可证

本项目仅供学习和研究使用。