# 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-22

## 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 融合，调用图扩展
- **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 | 启动全量索引 |
| `/index/tasks/{task_id}` | GET | 查询任务状态 |
| `/index/tasks/replay` | POST | 重放失败的任务 |
| `/search` | POST | 语义搜索 |

## 搜索示例

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

## 项目结构

```
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` |

## 许可证

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