# docx-3l-extraction-skill

> 三层定位抓取 Skill（正则→Embedding→LLM），用于精准定位文档章节

- Author: Jianan-Huang0609
- Repository: Jianan-Huang0609/skill_Diff_Comparison
- Version: 20260125223738
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/Jianan-Huang0609/skill_Diff_Comparison
- Web: https://mule.run/skillshub/@@Jianan-Huang0609/skill_Diff_Comparison~docx-3l-extraction-skill:20260125223738

---

---
name: docx-3l-extraction-skill
description: 三层定位抓取 Skill（正则→Embedding→LLM），用于精准定位文档章节
---

# 三层定位抓取 Skill

## 概述

本 Skill 实现了设计文档中定义的三层定位逻辑，用于解决章节标题不规范导致的定位失败问题。

## 三层定位逻辑

```
┌─────────────────────────────────────────────────────────────┐
│  输入: 目标章节名                                            │
├─────────────────────────────────────────────────────────────┤
│  L1: 正则/精确匹配                                          │
│      └─ 匹配成功 → 返回位置                                  │
│      └─ 匹配失败 → 进入 L2                                   │
├─────────────────────────────────────────────────────────────┤
│  L2: Embedding Top1 > 0.85?                                 │
│      └─ 分值足够 → 返回位置                                  │
│      └─ 分值过低 → 进入 L3                                   │
├─────────────────────────────────────────────────────────────┤
│  L3: LLM Few-shot 推理                                      │
│      └─ 推理成功 → 返回位置                                  │
│      └─ 推理失败 → 标记为未找到/人工处理                      │
└─────────────────────────────────────────────────────────────┘
```

## 核心类

### TriLayerExtractor

```python
from scripts.multi_layer_extractor import TriLayerExtractor

extractor = TriLayerExtractor(
    config_path="config/multi_layer_config.yaml",
    embedding_config="config/embedding.json",
    llm_config="config/4o.json"
)

result = extractor.extract_section("2.1 临床评价", full_text)
# 返回: {"success": True, "layer": "L1", "matched_text": "..."}
```

## 配置文件

### multi_layer_config.yaml

```yaml
thresholds:
  vector_min_score: 0.85   # L2 最低相似度阈值
  llm_confidence_min: 0.90 # L3 置信度阈值

regex_patterns:
  chapter_heading: "^(第[一二三四五六七八九十]章|\\d+\\.\\d+)"
  section_title: "^[\\u4e00-\\u9fa5]{2,10}$"
```

### embedding.json (敏感信息)

```json
{
  "azure_api_key": "${AZURE_OPENAI_API_KEY}",
  "azure_endpoint": "${AZURE_OPENAI_ENDPOINT}",
  "azure_deployment": "text-embedding-3-small",
  "api_version": "2024-02-01"
}
```

### 4o.json (敏感信息)

```json
{
  "azure_api_key": "${AZURE_OPENAI_API_KEY}",
  "azure_endpoint": "${AZURE_OPENAI_ENDPOINT}",
  "azure_deployment": "gpt-4o",
  "api_version": "2024-02-01"
}
```

---

## LEFA 后端集成

本 Skill 作为 `docx-extraction-skill` 的增强模块，在正则匹配失败时提供语义定位能力。

### 调用时机

```python
# docx-extraction-skill/scripts/extractor.py
from docx_3l_extraction_skill.scripts.multi_layer_extractor import TriLayerExtractor

def locate_section(target_name, doc_text):
    # L1: 先尝试正则
    result = regex_match(target_name, doc_text)
    if result:
        return result

    # L2+L3: 使用三层定位
    extractor = TriLayerExtractor(...)
    return extractor.extract_section(target_name, doc_text)
```

---

## 周一测试计划

### Phase 1: API 连通性验证
```bash
cd docx-3l-extraction-skill
python verify_apis.py
```

### Phase 2: 语义定位测试
```bash
python scripts/multi_layer_extractor.py
```

测试用例：
- 精确匹配："2.1 产品描述" → 应该在 L1 命中
- 语义匹配："临床表现" → 应该在 L2 命中 (相似度 > 0.85)
- 推理匹配："设备的用电量是多少" → 应该在 L3 命中

### Phase 3: 集成测试
1. 验证与 `docx-extraction-skill` 的数据接口
2. 确认阈值配置是否需要调整

---

## API 接口配置

### 环境变量（推荐）

```bash
export AZURE_OPENAI_ENDPOINT="https://xxx.openai.azure.com"
export AZURE_OPENAI_API_KEY="your-api-key"
export AZURE_EMBEDDING_DEPLOYMENT="text-embedding-3-small"
export AZURE_LLM_DEPLOYMENT="gpt-4o"
```

### 配置文件说明

| 文件 | 用途 | 敏感信息 |
|-----|------|---------|
| `config/multi_layer_config.yaml` | 阈值和正则配置 | 无 |
| `config/embedding.json` | Embedding API 配置 | ⚠️ 包含 API Key |
| `config/4o.json` | LLM API 配置 | ⚠️ 包含 API Key |

---

## 降级策略

| 层级 | 主策略 | 降级策略 |
|-----|-------|---------|
| L2 Embedding | Azure OpenAI | 本地 sentence-transformers |
| L3 LLM | GPT-4o | GPT-4o-mini → 纯正则 |
| Vector DB | Milvus (未来) | 内存计算 (当前) |

---

## 依赖

```
pyyaml>=6.0
requests>=2.28.0
numpy>=1.24.0
sentence-transformers>=2.2.0  # 本地 Embedding 降级
openai>=1.0.0                  # OpenAI API
```

---

## 已知问题

1. **重复 main() 函数**：`multi_layer_extractor.py` 末尾有两个 `main()` 定义，需要删除重复代码
2. **内存向量计算**：当前未集成向量数据库，大文档可能性能不佳
3. **配置文件硬编码**：部分配置文件包含 API Key，应改为环境变量