# LER

**Repository Path**: sun__ye/ler

## Basic Information

- **Project Name**: LER
- **Description**: 基于大模型的实体识别分类工具集
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://ler.ye-sun.com/
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-03-04
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LER：大模型驱动的智能实体识别与分类分级工具集

LER（LLM-based Entity Recognition）面向钢铁行业等结构化数据场景，将样本库、分类分级标准、检索增强、提示词构建、大模型调用、结果解析和性能评估组织成一条可复用的工作流。项目同时提供命令行工具、FastAPI 服务和 Streamlit WebUI，适合离线实验、批量分类、结果复核以及团队协作。

LER 的设计重点是**可追溯的分类任务**：每次任务都会保存输入分块、实际使用的配置、检索到的样例、完整提示词、模型原始输出、解析结果和评估结果，便于复现实验、定位错误并继续迭代样本。

## 能力概览

- **样本库管理**：导入 CSV/XLSX 标注数据，清洗并按表组织样本，生成可供检索的样本目录。
- **分类标准管理**：解析分类分级标准，保存标准化 CSV/JSON，并在 WebUI 中查看表格和树状结构。
- **项目与任务管理**：将一个样本库和一个分类标准绑定为项目，为项目配置模型、RAG 和提示词参数，并按任务保存运行记录。
- **检索增强与提示词构建**：支持 BM25、BERT 和随机示例检索，按输入数据、分类标准和示例生成结构化提示词。
- **多模型调用**：支持 OpenAI、DeepSeek、阿里云以及兼容 OpenAI API 的本地模型服务。
- **结果处理与评估**：将模型文本输出转换为 CSV；输入包含标注时，自动计算分级准确率并生成评估文件。
- **批量与可恢复执行**：输入表格会按表分块，可配置多进程执行；任务支持查看、重新执行和继续未完成任务。
- **可视化复核**：WebUI 展示任务进度、分级准确率、分块结果、提示词、调用记录和可下载的汇总结果。

## 总览与工作流

![LER architecture and workflow](./ler-overview.svg)

上图从左到右对应一次分类任务的完整生命周期：

1. **数据准备层**：`samplebase` 保存已标注样本，`category` 保存分类分级标准。两者可以独立导入，也可以通过一次 `samplebase update` 完成解析和清洗。
2. **任务配置层**：`project` 将样本库、分类标准和模型参数组合成可复用配置；每次 `classify` 执行都会在项目下创建递增的 `task` 目录。
3. **分类执行层**：`prompt` 汇总输入数据、标准和检索样例，`rag` 选择相似示例，`llm` 调用远程或本地模型，`result` 将文本响应解析为结构化结果。
4. **评估迭代层**：有标注的输入会进入 `rate`，输出分级准确率和错误明细；用户可下载结果、筛选易错样本、补充样本库后再次运行任务。
5. **持久化层**：所有配置和运行产物默认写入 `~/.ler/`。任务目录保留 `task.json`、`prompt.json`、`call.json`、`llm_output.*` 和 `rate.csv`，因此一次实验可以被审计和复盘。

### `~/.ler/` 数据组织

```text
~/.ler/
├── config/
│   ├── global.yaml       # 激活项目及项目参数
│   ├── env.yaml          # 模型 API 密钥
│   └── retrieval.yaml    # 输入列、标准列和检索模型配置
├── samplebase/
│   ├── <name>.csv        # 样本索引/原始汇总
│   └── <name>/           # 清洗后按表拆分的样本
├── category/
│   ├── <name>.csv        # 标准表
│   └── <name>.json       # 标准树
└── project/<project>/<task>/
    ├── task.json         # 任务配置、进度和状态
    ├── splits/           # 输入分块
    ├── <split>/          # 每个分块的调用与结果
    ├── llm_output.csv    # 合并后的分类结果
    └── rate.csv          # 合并后的评估结果（有标注时生成）
```

## 安装

LER 目前按 Python 3.9 维护，RAG 和本地模型相关依赖包含 PyTorch、Transformers 等组件，建议在独立虚拟环境中安装。

```bash
git clone https://gitee.com/sun__ye/ler.git
cd ler
conda create -n ler python=3.9
conda activate ler
python -m pip install -e .
```

安装后检查命令行入口：

```bash
ler --help
```

首次运行会初始化 `~/.ler/`。模型 API 密钥可写入 `~/.ler/config/env.yaml`，项目、样本库和分类标准默认配置位于 `~/.ler/config/global.yaml`。也可以用 `ler env set`、`ler project set` 等命令修改，不必手动编辑 YAML。

## 最小命令行流程

下面的流程使用一个分类标准文件和一个标注样本文件建立默认数据集，再提交分类任务。文件格式要求见[用户手册](./用户手册.md)。

```bash
# 解析分类标准和标注样本，并清洗样本库
ler samplebase update \
  --sample-path test/sample_files/分类分级数据1.6.xlsx \
  --category-path test/sample_files/标准测试样例.xlsx

# 使用默认项目执行分类；输入可以是 CSV 文件或 CSV 分块目录
ler classify path/to/input.csv

# 查看任务、结果和评估
ler task list
ler task show 1
ler task rate 1
```

`ler classify` 会异步创建任务并启动执行。项目配置中的 `model`、`local_api_url`、`rag`、`shot`、`num_beams` 和 `threads` 决定实际运行方式；若输入文件包含完整标注列，任务完成后会自动生成准确率报告。

当前分类流水线以 CSV 为主要输入，字段名称和四级分类列由 `ler/config/retrieval.yaml` 控制；标注样本的最小单位是字段，样本与标准通过数据资源说明字段匹配。XLSX 主要用于导入样本库和分类标准。具体列名、清洗规则和四级标准要求请以[用户手册](./用户手册.md)为准。

常用底层命令还包括：

```bash
ler rag input.csv --rag bm25 --shot 3       # 只检索示例
ler prompt input.csv -o prompt.json         # 生成提示词
ler llm -i prompt.json -o llm_output.txt    # 调用模型
ler result llm_output.txt -o llm_output.csv # 解析模型输出
ler rate llm_output.csv labeled.csv         # 对照标注评估
```

## WebUI、CLI 与 API

### WebUI 能做什么

WebUI 是面向数据准备和任务复核的可视化入口，当前包含三个页面：

- **数据分类分级项目**：新建或选择项目；查看绑定的样本库和分类标准；修改项目参数；上传 CSV 创建任务；查看任务进度、分块执行情况、分级准确率和汇总结果；重新执行任务或下载 `rate.csv`。
- **标准库管理**：上传 CSV/XLSX 分类标准；查看标准元信息和标准表；通过树状图检查分类层级；删除不再使用的标准。
- **样本库管理**：上传 CSV/XLSX 标注样本并选择分类标准；查看样本库元信息和样本表；删除样本库。

任务详情中可以展开查看每个分块的 `call.json`、`prompt.json` 和 `llm_output.csv`，因此 WebUI 不只是提交任务，也可用于复核模型输入、输出和评估依据。

### 启动方式

只启动 Streamlit WebUI：

```bash
./run_webui.sh
# 或：streamlit run main_streamlit.py
```

同时启动 FastAPI 和 WebUI：

```bash
./run.sh
```

`run.sh` 默认将 FastAPI 运行在 `http://localhost:5104`，将 Streamlit 运行在 `http://localhost:5105`。也可以分别启动：

```bash
python app.py                         # FastAPI，默认 5104
streamlit run main_streamlit.py      # Streamlit，默认 8501
```

FastAPI 文档地址为 `http://localhost:5104/docs`，OpenAPI JSON 地址为 `http://localhost:5104/openapi.json`。

### 三层入口的关系

CLI 是核心业务入口，样本库、项目、任务、RAG、模型调用和结果评估都在 `ler/tool/` 中实现。Streamlit 页面直接调用这些 Python 函数，因此适合本机交互式使用；FastAPI 在 `app.py` 中将主要 CLI 能力包装为 HTTP 接口，适合外部系统提交文件、查询任务和集成自动化流程。三者共享 `~/.ler/` 配置和任务目录，但 WebUI 不依赖 FastAPI 才能运行。

## 文件索引

```text
README.md                 # 项目定位、架构、安装和快速开始
ler-overview.svg          # 项目流程与数据组织总览图
用户手册.md                # 完整用户手册：环境、模型、数据格式和故障排查
docs.md                   # Typer 自动生成的 CLI 命令参考
docs/README.md            # 文档导航、WebUI 说明和扩展阅读
docs/api-reference.md     # FastAPI HTTP 接口参考
app.py                    # FastAPI 应用与 OpenAPI 路由
main_streamlit.py         # Streamlit 多页面入口
web/                      # WebUI 页面和任务详情组件
ler/tool/                 # CLI 命令及分类主流程
ler/util/                 # 数据解析、检索、转换和通用工具
ler/config/               # 项目默认配置模板
test/                     # 样例数据、测试和测试说明
```

完整的参数、选项和返回值以独立文档为准：

- [用户手册](./用户手册.md)：部署本地模型、配置环境、输入文件规范、缓存目录和问题排查。
- [HTTP API 参考](./docs/api-reference.md)：FastAPI 路由、请求字段、任务轮询和 curl 示例。
- [CLI 参考](./docs.md)：由 Typer 生成的命令说明，覆盖 `llm`、`rag`、`prompt`、`classify`、`project`、`category`、`samplebase` 和 `task`。
- [文档导航与架构说明](./docs/README.md)：WebUI 页面、服务边界、开发入口和测试位置。

## 测试与开发

语法级检查：

```bash
python -m compileall ler web app.py main_streamlit.py
```

测试样例、输入文件约定和现有命令测试说明见 [`test/README.md`](./test/README.md)。提交代码前请确保新增命令的 docstring、参数默认值和返回结构与现有 CLI 风格一致，并避免把运行时缓存提交到仓库。

## 许可

本项目采用 MIT License，详见 [`LICENSE.md`](./LICENSE.md)。