# https://github.com/benseverndev-oss/goldenmatch 项目说明书
生成时间：2026-05-30 23:32:32 UTC
## 目录
- [首页 - Golden Suite 简介](#home)
- [快速开始](#quick-start)
- [系统架构](#architecture)
- [处理管道](#pipeline)
- [自动配置系统](#autoconfig)
- [学习记忆系统](#learning-memory)
- [Blocking 策略](#blocking)
- [评分系统](#scoring)
- [数据库集成](#database-integration)
- [SQL 扩展](#sql-extensions)
## 首页 - Golden Suite 简介
### 相关页面
相关主题：[快速开始](#quick-start), [系统架构](#architecture), [处理管道](#pipeline)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/README.md)
- [packages/python/goldenmatch/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/README.md)
- [packages/python/goldencheck/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldencheck/README.md)
- [packages/python/goldenflow/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenflow/README.md)
- [packages/python/infermap/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/infermap/README.md)
- [packages/typescript/goldencheck-types/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/typescript/goldencheck-types/README.md)
- [examples/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/examples/README.md)
- [packages/python/goldenmatch/examples/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/examples/README.md)
# 首页 - Golden Suite 简介
## 概述
Golden Suite（黄金套件）是一个**多语言数据质量与实体解析工具包**，专为 AI 原生应用设计。该套件采用模块化架构，将数据质量检测（GoldenCheck）、数据标准化（GoldenFlow）、实体匹配去重（GoldenMatch）和流程编排（GoldenPipe）整合为一个统一的生态系统。
核心价值主张：
- **零配置开箱即用**：支持 `pip install goldenmatch && goldenmatch dedupe customers.csv` 三行命令完成去重
- **多语言支持**：提供 Python、TypeScript/Node.js、Rust 原生扩展
- **AI 原生集成**：内置 MCP（Model Context Protocol）服务器，支持 Claude 等 AI Agent 调用
- **企业级性能**：v1.24.0 版本在 10M QIS 真实数据集上实现 81% 耗时 reduction（F1=0.9886 不变）
资料来源：[README.md:1-30](https://github.com/benseverndev-oss/goldenmatch/blob/main/README.md)
---
## 套件架构
### 核心组件一览
| 工具包 | 语言支持 | 核心功能 | 安装命令 |
|--------|----------|----------|----------|
| **GoldenMatch** | Python · TS | 实体解析、去重、模糊/精确/概率/LLM 匹配 | `pip install goldenmatch` / `npm i goldenmatch` |
| **GoldenCheck** | Python · TS | 数据质量扫描、编码检测、Unicode 验证、格式校验、异常检测 | `pip install goldencheck` / `npm i goldencheck` |
| **GoldenFlow** | Python · TS | 数据转换与标准化：电话、日期、地址、分类数据规范化 | `pip install goldenflow` |
| **GoldenPipe** | Python · TS | 编排器，将 Check → Flow → Match 串联为声明式流水线 | `pip install goldenpipe` |
| **InferMap** | Python · TS | 模式映射引擎 — 自动对齐异构数据源的列 | `pip install infermap` |
| **goldenmatch-extensions** | Rust | Postgres 扩展（pgrx）+ DuckDB UDF，SQL 原生模糊匹配 | 源码编译 |
| **dbt-goldensuite** | dbt · Python | dbt 质量门测试、校正 CRUD 宏 | `pip install dbt-goldensuite` |
| **goldencheck-action** | GitHub Action | CI 中的数据质量门控 + PR 评论 | 集成工作流 |
| **goldensuite-mcp** | Docker | MCP 容器，AI Agent 一站式调用入口 | `docker run ghcr.io/benseverndev-oss/goldensuite-mcp:latest` |
资料来源：[README.md:45-70](https://github.com/benseverndev-oss/goldenmatch/blob/main/README.md)
### 数据处理流水线
```mermaid
graph LR
A[原始数据] --> B[GoldenCheck
质量扫描]
B --> C[数据质量报告]
C --> D{通过质量门?}
D -->|否| E[修复建议]
E --> A
D -->|是| F[GoldenFlow
标准化转换]
F --> G[规范化数据]
G --> H[InferMap
模式映射]
H --> I[统一模式]
I --> J[GoldenMatch
实体解析]
J --> K[去重结果]
K --> L[GoldenPipe
编排输出]
L --> M[Golden Records
黄金记录]
N[MCP Agent] --> |调用| B
N --> |调用| F
N --> |调用| J
N --> |调用| L
```
### 多语言实现策略
Golden Suite 采用 **polyglot 架构**，每个包提供 Python 和 TypeScript 双实现：
```mermaid
graph TD
subgraph Python生态系统
P1[goldencheck]
P2[goldenflow]
P3[goldenmatch]
P4[goldenpipe]
P5[infermap]
end
subgraph TypeScript生态系统
T1[goldencheck]
T2[goldenflow]
T3[goldenmatch]
T4[goldenpipe]
T5[infermap]
end
subgraph Rust加速层
R1[goldenmatch-native
Rust/PyO3 abi3]
R2[goldenmatch_pg
Postgres pgrx]
end
P3 --> |可选| R1
P3 --> |可选| R2
```
**版本要求**：
- Python: 3.11+
- Node.js: ≥20
- Rust: 用于扩展编译
资料来源：[README.md:20-35](https://github.com/benseverndev-oss/goldenmatch/blob/main/README.md)
---
## 核心包详解
### GoldenMatch — 实体解析引擎
GoldenMatch 是套件的旗舰包，提供零配置实体解析能力。
**核心特性**：
| 特性 | 说明 |
|------|------|
| 模糊匹配 | 编辑距离、Jaro-Winkler、TF-IDF 向量化 |
| 精确匹配 | 精确哈希、分块（Blocking） |
| 概率匹配 | 贝叶斯概率模型 |
| LLM 匹配 | 大语言模型语义聚类 |
| 性能 | 10M 记录 502 秒完成（F1=0.9886） |
**安装方式**：
```bash
# Python
pip install goldenmatch
# TypeScript
npm install goldenmatch
# 启用原生加速（可选）
pip install "goldenmatch[native]"
```
**核心使用示例**：
```python
from goldenmatch import GoldenMatch
matcher = GoldenMatch()
result = matcher.dedupe("customers.csv")
result.save("deduplicated.csv")
```
资料来源：[packages/python/goldenmatch/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/README.md)
### GoldenCheck — 数据质量扫描
GoldenCheck 自动发现数据质量规则，无需手动编写。
**检测类型**：
- 编码问题（Encoding）、Unicode 问题
- 格式验证（Format Validation）
- 异常值检测（Anomaly Detection）
- 唯一性校验（Uniqueness）
- 空值处理（Nullability）
- 日期/时间字段（Temporal Order）
**领域包支持**：
GoldenCheck 支持社区贡献的领域类型定义：
| 领域 | 类型数量 | 包含类型 |
|------|----------|----------|
| Healthcare | 10 | NPI、ICD 编码、保险 ID、患者人口统计、CPT、DRG |
| Finance | 8 | 账号、路由号、CUSIP/ISIN、货币、交易 |
| E-commerce | 9 | SKU、订单 ID、追踪号、分类、快递 |
资料来源：[packages/python/goldencheck/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldencheck/README.md)
资料来源：[packages/typescript/goldencheck-types/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/typescript/goldencheck-types/README.md)
### GoldenFlow — 数据转换与标准化
GoldenFlow 提供 76 种数据转换函数，覆盖常见标准化场景。
**转换分类**：
| 类别 | 数量 | 典型转换 |
|------|------|----------|
| 文本转换 | 18 | strip、lowercase、normalize_unicode、fix_mojibake |
| 电话转换 | 5 | phone_e164、phone_national |
| 日期转换 | - | 多格式日期解析 |
| 地址转换 | - | 标准化地址格式 |
| 分类转换 | - | 枚举值规范化 |
资料来源：[packages/python/goldenflow/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenflow/README.md)
### InferMap — 模式映射引擎
InferMap 自动对齐不同数据源的列结构。
**典型应用场景**：
- 数据库迁移
- ETL 源目标映射
- 跨系统数据整合
**支持功能**：
- 自定义评分器（Custom Scorers）
- 领域字典（Domain Dictionaries）
- 校准（Calibration）
- 分数矩阵内省（Score Matrix Introspection）
资料来源：[packages/python/infermap/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/infermap/README.md)
### GoldenPipe — 流程编排器
GoldenPipe 将 Check → Flow → Match 整合为声明式流水线。
**编排模式**：
```python
from goldenpipe import Pipeline
pipeline = Pipeline(
check="data.csv",
flow="transforms.yaml",
match={"group_by": "customer_id"}
)
pipeline.run()
```
资料来源：[examples/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/examples/README.md)
---
## 快速入门
### 三分钟上手 GoldenMatch
```bash
# 安装
pip install goldenmatch
# 对 CSV 去重
goldenmatch dedupe customers.csv
```
或 Python 代码：
```python
from goldenmatch import GoldenMatch
# 3 行代码完成去重
matcher = GoldenMatch()
result = matcher.dedupe("customers.csv")
result.save("deduplicated.csv")
```
### TypeScript / Edge 运行环境
```typescript
import { GoldenMatch } from 'goldenmatch';
const matcher = new GoldenMatch();
const result = await matcher.dedupe("./customers.csv");
await result.save("./deduplicated.csv");
```
### 示例脚本
| 脚本 | 演示内容 | 依赖 |
|------|----------|------|
| `basic_dedupe.py` | 基础模糊匹配去重 | goldenmatch |
| `explain_match.py` | 字段级得分分解 | goldenmatch |
| `advanced_config.py` | 标准化、多级分块、加权匹配键 | goldenmatch |
| `evaluate_and_tune.py` | 准确率测量与阈值调优 | goldenmatch |
| `streaming_incremental.py` | 流式增量匹配 | goldenmatch |
| `multi_source_pipeline.py` | 多数据源统一 | goldenmatch |
| `pprl_healthcare.py` | 跨机构隐私保护匹配 | goldenmatch |
| `llm_product_matching.py` | LLM 聚类产品匹配 | goldenmatch, OPENAI_API_KEY |
| `agent_demo.py` | 自主 ER Agent | goldenmatch |
| `benchmark.py` | DQBench 基准测试 | goldenmatch, dqbench |
资料来源：[packages/python/goldenmatch/examples/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/examples/README.md)
---
## 高级功能
### MCP 服务器集成
Golden Suite 提供 MCP（Model Context Protocol）服务器，支持 AI Agent 直接调用。
**启动 MCP 服务器**：
```bash
docker run ghcr.io/benseverndev-oss/goldensuite-mcp:latest
```
**客户端调用示例**（Python）：
```python
# examples/python/06_mcp_client.py
from goldenpipe import MCPClient
client = MCPClient("http://localhost:8080")
result = await client.analyze("data.csv")
```
**客户端调用示例**（TypeScript）：
```typescript
// examples/typescript/03-mcp-client.ts
import { GoldenSuiteMCP } from '@benseverndev-oss/goldensuite-mcp';
const client = new GoldenSuiteMCP('http://localhost:8080');
const result = await client.analyze('data.csv');
```
资料来源：[examples/README.md:30-40](https://github.com/benseverndev-oss/goldenmatch/blob/main/examples/README.md)
### SQL / 数据仓库集成
```sql
-- DuckDB 示例
SELECT * FROM goldenflow_normalize('customers.csv', 'phone', 'phone_e164');
-- Postgres 扩展
SELECT goldenmatch_dedupe('customers', 'group_by' := 'customer_id');
```
**支持平台**：
- DuckDB：核心 API + GoldenFlow 转换函数
- Postgres：13 个 pgrx 函数 + goldenflow_* 转换 + memory_learn/memory_stats CRUD
资料来源：[examples/README.md:20-35](https://github.com/benseverndev-oss/goldenmatch/blob/main/examples/README.md)
### Airflow DAG 工作流
提供 12 个可立即部署的 DAG：
| DAG 类型 | 使用场景 |
|----------|----------|
| `golden_suite_daily_dedupe.py` | 每日定时去重 |
| `golden_suite_incremental.py` | 增量去重 |
| `golden_suite_warehouse_native.py` | 数据仓库原生处理 |
| `golden_suite_customer_360.py` | 客户 360 视图构建 |
| `golden_suite_pprl_linkage.py` | 隐私保护记录链接 |
| `golden_suite_schema_align.py` | 模式对齐 |
| `golden_suite_quality_gate.py` | 质量门控 |
| `golden_suite_review_worker.py` | 审核工作流 |
| `golden_suite_active_learning.py` | 主动学习 |
| `golden_suite_reverse_etl.py` | 反向 ETL |
| `golden_suite_backfill.py` | 数据回填 |
资料来源：[examples/README.md:15-25](https://github.com/benseverndev-oss/goldenmatch/blob/main/examples/README.md)
### dbt 集成
```bash
pip install dbt-goldensuite
```
提供功能：
- 质量门测试
- 校正 CRUD 宏
- GoldenCheck 断言
资料来源：[README.md:65-70](https://github.com/benseverndev-oss/goldenmatch/blob/main/README.md)
---
## 性能基准
| 版本 | 数据规模 | 耗时 | RSS | F1 | 优化内容 |
|------|----------|------|-----|-----|----------|
| v1.24.0 | 10M QIS | 502s | -18% | 0.9886 | ~15 个性能 PR、Chao1 基数感知、启发式规则扩展 |
| v1.16.0 | 5M | 9.94 min | 6.4 GB | - | bucket 后端路径 |
| v1.15.0 | 5M | ~50 min | 11.9 GB | - | 分块基准 |
**性能优化路径**：
```mermaid
graph LR
A[Chunked Path
50 min] --> B[v1.16.0
Bucket Path
10 min]
B --> C[v1.24.0
Rust 加速
502s]
style C fill:#90EE90
```
资料来源：[README.md:85-100](https://github.com/benseverndev-oss/goldenmatch/blob/main/README.md)
---
## 版本历史
### 最新版本：v1.24.0
- **性能突破**：10M QIS-bucket-realistic 场景下耗时从 2604s 降至 502s（-81%）
- **内存优化**：RSS 减少 18%
- **精度保持**：F1=0.9886 保持不变
- **优化项**：约 15 个性能 PR、Chao1 规模感知基数、启发式规则扩展、诊断工具
### 关键版本
| 版本 | 特性 |
|------|------|
| v1.24.0 | 81% 耗时 reduction、Chao1 基数感知 |
| v1.23.0 | 自动配置 recall、零标签提交默认 |
| v1.22.0 | 字段级黄金记录溯源 |
| v1.21.0 | 原生加速运行时（Rust） |
| v1.20.0 | 聚类决策调优器 |
| v1.19.0 | 原生加速、LLM 匹配改进 |
| v1.18.0 | 多语言支持完善 |
---
## 下一步
| 任务 | 资源 |
|------|------|
| 快速开始去重 | [`examples/python/01_quickstart_dedupe.py`](examples/python/01_quickstart_dedupe.py) |
| 构建数据质量流水线 | [`examples/python/02_full_suite_pipeline.py`](examples/python/02_full_suite_pipeline.py) |
| 多数据源统一 | [`examples/python/03_multi_source_unify.py`](examples/python/03_multi_source_unify.py) |
| TypeScript/Edge 运行时 | [`examples/typescript/01-quickstart.ts`](examples/typescript/01-quickstart.ts) |
| SQL/数据仓库 | [`examples/sql/`](examples/sql/) |
| AI Agent 集成 | [`examples/python/06_mcp_client.py`](examples/python/06_mcp_client.py) |
| Web UI 可视化 | `pip install goldenmatch[web]` 然后 `goldenmatch serve-ui ` |
---
## 快速开始
### 相关页面
相关主题：[首页 - Golden Suite 简介](#home)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/python/goldenmatch/examples/basic_dedupe.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/examples/basic_dedupe.py)
- [packages/python/goldenmatch/examples/zero_config_quickstart.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/examples/zero_config_quickstart.py)
- [packages/typescript/goldenmatch/examples/01-basic-dedupe.ts](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/typescript/goldenmatch/examples/01-basic-dedupe.ts)
- [examples/python/01_quickstart_dedupe.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/examples/python/01_quickstart_dedupe.py)
- [packages/python/goldenmatch/examples/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/examples/README.md)
# 快速开始
Goldenmatch 是 Golden Suite 数据质量工具套件的核心组件，提供零配置到高级定制的实体解析（Entity Resolution）能力。本页面将帮助你在 5 分钟内完成首次去重任务。
## 安装
### Python 环境
```bash
pip install goldenmatch
```
可选依赖：
```bash
# Web UI 可视化界面
pip install "goldenmatch[web]"
# 原生加速运行时（Rust/PyO3）
pip install "goldenmatch[native]"
# LLM 增强功能
pip install "goldenmatch[anthropic]"
```
### TypeScript / Node.js 环境
```bash
npm install goldenmatch
```
**环境要求：**
- Python: 3.11+
- Node.js: >=20
## 核心概念
```mermaid
graph TD
A[输入数据] --> B[分块 Blocking]
B --> C[候选对生成]
C --> D[相似度评分]
D --> E[聚类 Clustering]
E --> F[黄金记录构建]
F --> G[去重结果输出]
H[配置调优] -.->|自动推荐| C
H -.->|自动推荐| D
H -.->|自动推荐| E
```
| 概念 | 说明 |
|------|------|
| **Blocking** | 将数据分块以减少比较次数，避免 O(n²) 全量比较 |
| **Scoring** | 对候选对进行相似度评分，支持模糊匹配、精确匹配、概率模型 |
| **Clustering** | 将相似记录聚类为同一实体组 |
| **Golden Record** | 从多个重复记录中选出最佳值作为最终输出 |
## 方法一：零配置快速去重（推荐新手）
### Python 快速上手
```python
from goldenmatch import Goldenmatch
# 一行代码完成去重
gm = Goldenmatch()
result = gm.dedupe("customers.csv")
result.write_csv("deduplicated.csv")
```
资料来源：[packages/python/goldenmatch/examples/zero_config_quickstart.py:1-10]()
### TypeScript 快速上手
```typescript
import { Goldenmatch } from "goldenmatch";
const gm = new Goldenmatch();
const result = await gm.dedupe("customers.csv");
await result.writeCSV("deduplicated.csv");
```
资料来源：[packages/typescript/goldenmatch/examples/01-basic-dedupe.ts:1-20]()
### 命令行快速上手
```bash
# 最简命令
goldenmatch dedupe customers.csv
# 指定输出
goldenmatch dedupe customers.csv --output deduplicated.csv
```
## 方法二：基础配置去重
### Python 示例
```python
from goldenmatch import Goldenmatch, Config
config = Config()
config.match.name_fields = ["first_name", "last_name"]
config.match.email_field = "email"
config.blocking.name_blocker = True
gm = Goldenmatch(config)
result = gm.dedupe("customers.csv")
result.write_csv("deduplicated.csv")
```
资料来源：[packages/python/goldenmatch/examples/basic_dedupe.py:1-30]()
### 基础配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `name_fields` | list[str] | `[]` | 姓名字段列表 |
| `email_field` | str | `None` | 邮箱字段 |
| `phone_field` | str | `None` | 电话字段 |
| `address_fields` | list[str] | `[]` | 地址字段 |
| `name_blocker` | bool | `False` | 启用姓名分块 |
| `email_blocker` | bool | `False` | 启用邮箱分块 |
## 方法三：高级配置去重
### 自定义匹配键
```python
from goldenmatch import Goldenmatch, Config, MatchKey
config = Config()
config.match.keys = [
MatchKey(fields=["email"], weight=0.5),
MatchKey(fields=["phone"], weight=0.3),
MatchKey(fields=["first_name", "last_name"], weight=0.2),
]
```
### 多轮分块策略
```python
config.blocking.passes = [
{"type": "email"},
{"type": "name_soundex"},
{"type": "phone_last4"},
{"type": "fuzzy_name"},
]
```
### 权重调优
```python
config.match.field_weights = {
"email": 0.5,
"phone": 0.3,
"first_name": 0.1,
"last_name": 0.1,
}
```
## 工作流程图
```mermaid
graph LR
A[原始数据] --> B[数据加载]
B --> C{配置方式}
C -->|零配置| D[自动推断配置]
C -->|自定义| E[用户指定配置]
D --> F[去重执行]
E --> F
F --> G[结果评估]
G --> H{评估结果}
H -->|不满意| I[调整配置]
I --> F
H -->|满意| J[输出结果]
```
## 输出结果格式
### 返回对象结构
| 属性 | 类型 | 说明 |
|------|------|------|
| `clusters` | DataFrame | 聚类结果，包含 `cluster_id`、`member_id`、`is_golden` |
| `golden_records` | DataFrame | 黄金记录数据 |
| `statistics` | dict | 匹配统计信息 |
### 输出字段说明
| 字段 | 说明 |
|------|------|
| `__row_id__` | 原始行号 |
| `__cluster_id__` | 所属聚类 ID |
| `__is_golden__` | 是否为黄金记录 |
| `__match_score__` | 匹配得分 |
| `__source_row_id__` | 字段来源行号（启用 provenance 时） |
## 性能基准
| 数据规模 | 推荐配置 | 预期耗时 | 内存峰值 |
|---------|---------|---------|---------|
| 10K 记录 | 零配置 | <10 秒 | <500 MB |
| 100K 记录 | bucket 分块 | <2 分钟 | <2 GB |
| 1M 记录 | bucket 分块 + native | <10 分钟 | <5 GB |
| 5M 记录 | bucket 分块 + native | ~10 分钟 | ~6.4 GB |
| 10M 记录 | QIS-bucket-realistic | ~8 分钟 | 优化中 |
> v1.24.0 性能数据：10M QIS-bucket-realistic 场景下耗时从 2604s 降至 502s（-81%），内存降低 18%。
## 常见问题
### Q: 零配置模式是否总是最优选择？
不是。零配置适合快速原型验证。对于生产环境，建议：
- 使用 `evaluate_and_tune.py` 示例进行精度调优
- 启用 `autoconfig` 功能自动优化阈值
### Q: 如何处理隐私敏感数据（PPRL）？
使用 `pprl_healthcare.py` 示例，通过隐私保护记录链接技术实现跨机构匹配，无需共享原始数据。
### Q: 支持哪些数据源？
- CSV 文件
- Parquet 文件
- 数据库表（Postgres、DuckDB）
- Python DataFrame / TypeScript Record[]
## 下一步
- 查看 [示例脚本](../packages/python/goldenmatch/examples/README.md) 了解完整功能
- 使用 [Web UI](https://github.com/benseverndev-oss/goldenmatch/wiki/Web-UI) 可视化分析结果
- 集成 [MCP Server](https://github.com/benseverndev-oss/goldenmatch/wiki/MCP-Server) 用于 AI 工作流
- 了解 [性能调优](https://github.com/benseverndev-oss/goldenmatch/wiki/Performance-Tuning) 最佳实践
---
## 系统架构
### 相关页面
相关主题：[首页 - Golden Suite 简介](#home), [处理管道](#pipeline), [自动配置系统](#autoconfig)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/python/goldenmatch/docs/architecture.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/docs/architecture.md)
- [packages/python/goldenmatch/goldenmatch/core/pipeline.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/pipeline.py)
- [packages/python/goldenmatch/goldenmatch/core/autoconfig_controller.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig_controller.py)
- [packages/python/goldenmatch/goldenmatch/core/memory/learner.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/memory/learner.py)
- [packages/python/goldenmatch/goldenmatch/backends/duckdb_backend.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/backends/duckdb_backend.py)
# 系统架构
## 概述
Goldenmatch 是一个多语言数据质量和实体解析（Entity Resolution）工具包，提供从数据清洗、质量检查到记录去重的完整解决方案。系统采用模块化架构设计，核心用 Python 实现，辅以 TypeScript/Node.js 实现和 Rust 原生加速运行时。 资料来源：[README.md](../README.md)
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Golden Suite 架构全景 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ GoldenCheck │ → │ GoldenFlow │ → │ GoldenMatch │ → │ GoldenPipe │ │
│ │ 数据质量扫描 │ │ 数据标准化 │ │ 实体解析/去重 │ │ 流程编排 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ↑ ↑ │
│ └──────────────── InferMap ──────────────────────────────┘ │
│ (Schema 映射) │
└─────────────────────────────────────────────────────────────────────────────┘
```
## 核心模块
### 核心处理管道（Pipeline）
Pipeline 是 Goldenmatch 的主处理引擎，负责协调整个实体解析流程。 资料来源：[core/pipeline.py:1-50]()
```mermaid
graph TD
A[输入数据] --> B[数据加载]
B --> C[配置加载]
C --> D[数据预处理]
D --> E[Blocking 分块]
E --> F[候选对生成]
F --> G[相似度评分]
G --> H[聚类]
H --> I[Golden Record 构建]
I --> J[结果输出]
K[Learning Memory] -.-> E
K -.-> G
K -.-> H
L[AutoConfig] -.-> C
L -.-> I
```
核心组件包括：
| 模块 | 文件路径 | 功能描述 |
|------|----------|----------|
| Pipeline | `core/pipeline.py` | 主处理引擎，协调整个流程 |
| AutoConfig | `core/autoconfig_controller.py` | 自动配置调优 |
| Memory Learner | `core/memory/learner.py` | 学习记忆系统 |
| Backends | `backends/*.py` | 多后端支持（Polars/DuckDB） |
### 自动配置控制器（AutoConfig Controller）
AutoConfig 是 Goldenmatch 的智能配置系统，能够根据数据特征自动调整匹配参数。该系统从 v1.20.0 开始引入聚类决策调谐器（cluster-decision tuner），是 Learning Memory 系列的第三个调谐器。 资料来源：[core/autoconfig_controller.py:1-100]()
```python
# 核心自动配置流程伪代码
class AutoConfigController:
def __init__(self, config, dataset_profile):
self.recall_tuner = RecallTuner()
self.precision_tuner = PrecisionTuner()
self.cluster_threshold_tuner = ClusterThresholdTuner()
def tune(self, feedback: FeedbackData) -> TunedConfig:
# 基于反馈调整配置
pass
```
**配置调谐器类型：**
| 调谐器 | 级别 | 功能 |
|--------|------|------|
| MemoryLearner | Pair 级 | 基于配对级别的 approve/reject 决策 |
| FieldStrategyTuner | Field 级 | 字段级策略优化 |
| ClusterThresholdTuner | Cluster 级 | 聚类级决策阈值自动配置 |
从 v1.23.0 起，系统默认使用零标签置信度（zero-label confidence）进行自动配置提交，控制器优先选择具有更高 `-overall_confidence` 的候选方案。 资料来源：[core/autoconfig_controller.py:100-150]()
### 学习记忆系统（Learning Memory）
Learning Memory 是 Goldenmatch 的自适应学习机制，能够从用户反馈中学习并优化匹配策略。 资料来源：[core/memory/learner.py:1-80]()
```mermaid
graph LR
A[用户决策] --> B[记忆存储]
B --> C[模式学习]
C --> D[策略更新]
D --> E[下次匹配]
E --> A
```
记忆系统支持三种学习模式：
| 模式 | 输入 | 输出 |
|------|------|------|
| 配对学习 | approve/reject 决策 | Pair-level 规则 |
| 字段学习 | 字段匹配反馈 | FieldStrategy |
| 聚类学习 | Cluster-level 决策 | 决策阈值建议 |
v1.22.0 引入了 Field-level golden-record provenance 功能，每个字段字典都包含 `source_row_id`，追踪值的来源记录。 资料来源：[core/memory/learner.py:80-150]()
## 后端架构
### 多后端支持
Goldenmatch 支持多种数据处理后端，可根据数据规模选择最优方案。 资料来源：[backends/duckdb_backend.py:1-60]()
| 后端 | 适用场景 | 特点 |
|------|----------|------|
| Polars | 中小规模数据 | 纯 Python，零依赖 |
| DuckDB | 大规模数据 | 列式存储，高性能 |
| Native (Rust) | 超大规模数据 | PyO3 abi3，编译加速 |
```python
# 后端选择逻辑
def get_backend(data_size: int, config: Config) -> Backend:
if config.use_native and has_native_runtime():
return NativeBackend()
elif data_size > 5_000_000:
return DuckDBBackend()
else:
return PolarsBackend()
```
### 原生加速运行时
从 v1.21.0 起，Goldenmatch 支持可选的原生加速运行时（goldenmatch-native），这是一个用 Rust/PyO3 abi3 编写的编译加速引擎。 资料来源：[README.md](../README.md)
```bash
# 安装原生加速
pip install "goldenmatch[native]"
```
安装后系统会自动发现并使用原生内核，无需额外配置。v1.24.0 的性能数据显示，在 10M QIS-bucket-realistic 数据集上，使用原生加速后处理时间从 2604 秒降至 502 秒（-81%），同时 RSS 内存减少 18%。 资料来源：[CHANGELOG.md](../CHANGELOG.md)
## 扩展生态系统
### Rust 扩展
Goldenmatch 提供 Postgres 扩展（goldenmatch_pg）和 DuckDB UDFs，支持在数据库内直接进行 SQL 原生模糊匹配。 资料来源：[packages/rust/extensions/README.md]()
| 函数 | 功能 |
|------|------|
| `goldenmatch_suggest_threshold()` | Otsu 阈值建议 |
| `goldenmatch_detect_domain()` | 领域检测 |
| `goldenmatch_evaluate()` | 精确率/召回率评估 |
| `goldenmatch_train_em()` | EM 概率训练 |
### TypeScript/Node.js 实现
Goldenmatch 提供完整的 TypeScript 实现，支持在 Node.js、Edge Runtime 和 Next.js Server Components 中使用。 资料来源：[packages/typescript/goldenmatch/README.md]()
```typescript
// TypeScript 使用示例
import { GoldenMatch } from 'goldenmatch';
const matcher = new GoldenMatch();
const results = await matcher.dedupe(records);
```
### MCP 服务器集成
Goldenmatch 支持 Model Context Protocol，可与 Claude Desktop 等 AI 工具无缝集成。
```bash
pip install "goldenmatch[mcp]"
```
## 数据流架构
```mermaid
graph TD
subgraph 输入层
A[CSV/Parquet]
B[DataFrame]
C[SQL Table]
D[API/Streaming]
end
subgraph 处理层
E[GoldenCheck 扫描]
F[GoldenFlow 标准化]
G[InferMap Schema映射]
H[GoldenMatch 去重]
end
subgraph 输出层
I[Golden Records]
J[Cluster 映射]
K[Provenance 追踪]
L[MCP Tools]
end
A --> E
B --> E
C --> G
D --> F
E --> F
F --> G
G --> H
H --> I
H --> J
J --> K
H --> L
```
## 性能优化
### 阻塞策略（Blocking）
Goldenmatch 使用多轮阻塞策略减少比较次数：
| 策略 | 适用场景 | 性能提升 |
|------|----------|----------|
| QIS Bucket | 大规模数据 | ~100x |
| LSH | 近似匹配 | ~50x |
| Sorted Neighborhood | 有序数据 | ~20x |
v1.24.0 引入的 QIS-bucket-realistic 阻塞策略，结合 Chao1 基数估计和启发式规则扩展，在 10M 记录规模下实现了 81% 的耗时减少。 资料来源：[CHANGELOG.md](../CHANGELOG.md)
### 内存管理
系统采用多种内存优化策略：
1. **流式处理**：支持增量处理大规模数据
2. **向量化操作**：单 group-by-per-column 模式减少中间结果
3. **Provenance 追踪**：可选的字段级溯源，不影响核心性能
## 配置体系
```python
# 典型配置结构
config = {
"match": {
"fields": ["name", "address", "phone"],
"thresholds": {"fuzzy": 0.85, "exact": 0.95}
},
"blocking": {
"strategy": "qis_bucket",
"passes": 3
},
"memory": {
"enabled": True,
"learn_from_feedback": True
},
"output": {
"lineage_provenance": False
}
}
```
## 相关文档
- [快速开始指南](./quickstart.md) - 5 分钟上手
- [API 参考](./api-reference.md) - 完整的 API 文档
- [配置参考](./configuration.md) - 所有配置选项说明
- [性能调优](./performance.md) - 大规模数据优化建议
---
## 处理管道
### 相关页面
相关主题：[系统架构](#architecture), [Blocking 策略](#blocking), [评分系统](#scoring)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/python/goldenmatch/goldenmatch/core/pipeline.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/pipeline.py)
- [packages/python/goldenmatch/goldenmatch/core/blocker.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/blocker.py)
- [packages/python/goldenmatch/goldenmatch/core/scorer.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/scorer.py)
- [packages/python/goldenmatch/goldenmatch/core/cluster.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/cluster.py)
- [packages/python/goldenmatch/goldenmatch/core/golden.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/golden.py)
- [packages/python/goldenpipe/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenpipe/README.md)
- [packages/python/goldenmatch/examples/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/examples/README.md)
# 处理管道
Goldenmatch 的处理管道是将脏乱数据转化为干净、去重、合并的黄金记录（Golden Records）的完整工作流。该管道通过阻塞（Blocking）、评分（Scoring）、聚类（Clustering）三个核心阶段，结合可插拔的标准化和匹配策略，实现高效实体解析。
## 管道架构概览
```mermaid
graph TD
A[原始数据输入] --> B[数据标准化]
B --> C[阻塞分块]
C --> D[候选对生成]
D --> E[记录评分]
E --> F[聚类分组]
F --> G[黄金记录构建]
G --> H[输出结果]
C -->|QIS-bucket 优化| C
E -->|概率模型| E
F -->|图遍历| F
G -->|溯源追踪| G
```
### 管道核心阶段
| 阶段 | 功能 | 关键文件 |
|------|------|----------|
| 标准化 (Standardization) | 规范化字段格式（电话、日期、地址） | `goldenflow` 包 |
| 阻塞 (Blocking) | 减少候选对数量，避免 O(n²) 全比较 | `blocker.py` |
| 评分 (Scoring) | 计算记录对相似度分数 | `scorer.py` |
| 聚类 (Clustering) | 将相似记录分组为实体簇 | `cluster.py` |
| 黄金记录 (Golden Records) | 从簇中选择代表性记录 | `golden.py` |
## 阻塞机制 (Blocking)
阻塞是性能优化的关键步骤，通过将数据划分为"块"来限制需要比较的记录对数量。
### 阻塞策略
```python
# 典型阻塞配置
blocking_keys = [
"soundex(last_name)", # 姓氏语音编码
"first_two(postal_code)", # 邮编前两位
"first_five(phone)", # 电话前五位
]
```
### QIS-Bucket 优化
v1.24.0 版本引入 QIS-bucket（Quality-Invariant Scaling）优化，实现 10M 记录从 2604 秒降至 502 秒（-81% wall time），同时保持 F1=0.9886 不变。资料来源：[packages/python/goldenmatch/CHANGELOG.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/CHANGELOG.md)
```mermaid
graph LR
A[原始数据] --> B[启发式规则扩展]
B --> C[Chao1 基数估计]
C --> D[规模感知分块]
D --> E[候选对集合]
```
### 阻塞类型
| 类型 | 描述 | 适用场景 |
|------|------|----------|
| 精确阻塞 | 块键完全匹配 | 高质量标准化的数据 |
| 模糊阻塞 | 块键相似（如 soundex） | 名称变体、拼写错误 |
| 锚定阻塞 | 多块键交集 | 极高数据量（10M+） |
| 自适应阻塞 | 根据数据特征自动选择 | 异构数据源 |
## 评分系统 (Scoring)
评分阶段计算每对候选记录的相似度分数，支持多种评分模型。
### 评分器类型
| 评分器 | 描述 | 适用字段 |
|--------|------|----------|
| `StringScorer` | 编辑距离、Jaro-Winkler | 姓名、地址 |
| `NumericScorer` | 绝对差、比率差 | 年龄、价格 |
| `DateScorer` | 日期差、格式差异 | 日期字段 |
| `ProbabilisticScorer` | Fellegi-Sunter EM 模型 | 混合字段 |
### 字段级评分配置
```python
field_config = {
"name": {"strategy": "fuzzy", "weight": 0.4},
"address": {"strategy": "tokenized", "weight": 0.3},
"phone": {"strategy": "normalized", "weight": 0.2},
"email": {"strategy": "exact", "weight": 0.1},
}
```
### LLM 增强评分
可选的 LLM 评分器使用大语言模型进行语义匹配，适用于产品名称等复杂文本字段：
```python
# 需要 OPENAI_API_KEY 或 ANTHROPIC_API_KEY
scorer = LLMScorer(provider="openai", model="gpt-4")
```
## 聚类算法 (Clustering)
聚类阶段将评分高于阈值的记录对合并为连通分量，形成实体簇。
### 聚类策略
| 策略 | 描述 | 阈值调优 |
|------|------|----------|
| 单一阈值 | 分数 > 阈值则合并 | `tune_decision_threshold()` |
| 簇级决策 | 考虑簇内整体质量 | v1.20.0 引入 |
| 概率决策 | 基于 EM 后验概率 | 需要训练数据 |
### 决策阈值调优
```python
from goldenmatch.core.autoconfig_cluster_threshold_tune import tune_decision_threshold
# 消费簇级 approve/reject 决策
threshold = tune_decision_threshold(feedback_data, clusters)
```
v1.20.0 引入了簇级决策调优器，是 Learning Memory 系列的第三个调优器。资料来源：[v1.20.0 Release](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.20.0)
## 黄金记录构建 (Golden Records)
黄金记录是从实体簇中选择或合并的最优代表记录。
### 存活策略 (Survivorship)
| 策略 | 描述 |
|------|------|
| `most_complete` | 选择非空字段最多的记录 |
| `most_recent` | 选择最新修改的记录 |
| `highest_confidence` | 选择来源可信度最高的记录 |
| `merged` | 字段级合并，取各记录最优值 |
### 溯源追踪 (Provenance)
v1.22.0 引入了字段级黄金记录溯源功能：
```python
golden_records = build_golden_records_batch(
clusters,
provenance=True # 启用溯源
)
# 每个字段包含 source_row_id，标识该字段值来自哪条原始记录
```
配置选项：
- `config.output.lineage_provenance`（默认 False）资料来源：[v1.22.0 Release](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.22.0)
## 性能优化
### 后端选择
| 后端 | 适用规模 | 性能特征 |
|------|----------|----------|
| `backend="chunked"` | < 1M | 内存友好，稳定性优先 |
| `backend="bucket"` | 1M - 10M | 5x wall 减少，2x RSS 减少 |
| `backend="native"` | > 5M | Rust/PyO3 编译加速 |
### 原生加速运行时
v1.21.0 引入了可选的原生加速运行时：
```bash
pip install "goldenmatch[native]"
```
goldenmatch-native 是用 Rust/PyO3 abi3 编译的运行时，包含聚类和块评分内核，goldenmatch 自动发现并使用。资料来源：[v1.21.0 Release](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.21.0)
### 推荐配置
| 数据规模 | 推荐配置 |
|----------|----------|
| < 100K | 默认配置，无需调优 |
| 100K - 1M | `backend="chunked"` |
| 1M - 5M | `backend="bucket"` |
| 5M - 10M | `backend="bucket"` + `backend="native"` |
| > 10M | 分区处理 + `backend="native"` |
## 配置参考
### 完整配置示例
```python
from goldenmatch import GoldenMatch
config = {
"blocking": {
"keys": ["soundex(last_name)", "first_two(zip)"],
"method": "qis_bucket", # v1.24.0 优化
},
"scoring": {
"fields": {
"name": {"strategy": "fuzzy", "weight": 0.5},
"address": {"strategy": "tokenized", "weight": 0.3},
"phone": {"strategy": "normalized", "weight": 0.2},
},
"method": "probabilistic", # 或 "rule_based"
},
"clustering": {
"decision_threshold": "auto", # 自动调优
},
"output": {
"golden_records": True,
"lineage_provenance": False,
},
}
matcher = GoldenMatch(config)
result = matcher.dedupe("customers.csv")
```
### 自动配置
管道支持零配置自动推断：
```python
# 自动配置召回率和零标签提交
matcher = GoldenMatch(auto_config=True)
# v1.23.0 改进：零标签置信度提交
# pick_committed 优先选择更高 -overall_confidence 的候选
```
v1.23.0 默认启用零标签置信度自动配置，在精度塌陷风险较高时自动回退。资料来源：[v1.23.0 Release](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.23.0)
## 与 GoldenPipe 的关系
GoldenPipe 是更上层的编排层，将 Check → Flow → Match 串联为声明式管道：
```mermaid
graph LR
A[GoldenCheck] --> B[GoldenFlow]
B --> C[GoldenMatch]
C --> D[输出]
E[GoldenPipe] -->|编排| A
E -->|编排| B
E -->|编排| C
```
### GoldenPipe 使用示例
```python
from goldenpipe import GoldenPipe
pipeline = GoldenPipe.from_config("pipeline.yml")
pipeline.run(
source="data/customers.csv",
output="data/deduplicated.csv"
)
```
GoldenPipe 支持 Airflow DAGs，提供 12 个开箱即用的 DAG 示例。资料来源：[examples/airflow/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/examples/airflow/README.md)
## 常见问题
### 内存溢出 (OOM)
对于超大数据集，使用分区处理或启用原生加速：
```python
matcher = GoldenMatch(backend="native")
```
### 精度下降
检查阻塞键是否过于宽松导致假阳性，或使用 LLM 增强评分。
### 阈值调优
使用 `evaluate_and_tune.py` 示例脚本，根据已知真值调整阈值。
---
## 自动配置系统
### 相关页面
相关主题：[系统架构](#architecture), [学习记忆系统](#learning-memory)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/python/goldenmatch/goldenmatch/core/autoconfig_controller.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig_controller.py)
- [packages/python/goldenmatch/goldenmatch/core/autoconfig.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig.py)
- [packages/python/goldenmatch/goldenmatch/core/autoconfig_cluster_threshold_tuner.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig_cluster_threshold_tuner.py)
- [packages/python/goldenmatch/goldenmatch/core/autoconfig_negative_evidence.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig_negative_evidence.py)
- [packages/python/goldenmatch/goldenmatch/core/autoconfig_history.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig_history.py)
# 自动配置系统
## 概述
自动配置系统（Auto-config）是GoldenMatch中的智能配置引擎，旨在消除实体解析任务中的手动调参工作。该系统通过分析数据特征、观察匹配行为、收集正负证据，自动推断最优的匹配阈值、阻塞策略和字段权重配置。
自动配置系统的核心价值在于：
- **零配置启动**：用户无需深入理解匹配算法细节即可获得高质量结果
- **自适应优化**：根据数据规模、字段分布动态调整参数
- **持续学习**：通过历史决策记录不断改进配置建议
- **可解释性**：提供配置决策的置信度和推理依据
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig.py:1-50]()
## 系统架构
自动配置系统由多个协同工作的模块组成，形成完整的配置发现→评估→优化闭环。
```mermaid
graph TD
A[输入数据] --> B[autoconfig.py
特征提取]
B --> C[autoconfig_negative_evidence.py
负样本收集]
B --> D[autoconfig_history.py
历史经验]
C --> E[autoconfig_controller.py
控制器]
D --> E
E --> F[autoconfig_cluster_threshold_tuner.py
阈值调优]
F --> G[优化后的配置]
G --> H[实体解析引擎]
H --> I[结果反馈]
I --> D
```
### 核心模块职责
| 模块 | 职责 | 关键功能 |
|------|------|----------|
| `autoconfig.py` | 特征提取与配置生成 | 分析数据分布，生成初始候选配置 |
| `autoconfig_controller.py` | 配置调度与决策 | 管理配置生命周期，选择最优配置 |
| `autoconfig_cluster_threshold_tuner.py` | 阈值优化 | 根据聚类决策调整决策边界 |
| `autoconfig_negative_evidence.py` | 负证据收集 | 识别并记录明确的非匹配对 |
| `autoconfig_history.py` | 经验存储 | 持久化配置决策，支持增量学习 |
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig_controller.py:1-80]()
## 控制器模块
控制器是自动配置系统的核心调度器，负责协调各子模块并做出最终配置决策。
### 决策流程
```mermaid
graph LR
A[接收候选配置] --> B{健康度排名}
B --> C{零标签配置?}
C -->|是| D[优先置信度]
C -->|否| E[优先质量分离]
D --> F[pick_committed]
E --> F
F --> G[输出最终配置]
```
### pick_committed 决策逻辑
控制器采用多级排序策略选择最终提交的配置：
1. **第一排序键**：健康度排名（health_rank）—— 优先选择数据质量更优的配置
2. **第二排序键**：零标签特征—— 携带 `zero_label` 配置文件的特殊处理
3. **第三排序键**（零标签场景）：`-overall_confidence` —— 选择整体置信度更高的候选
4. **第四排序键**（非零标签场景）：`-mass_separation` —— 选择质量分离度更高的候选
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig_controller.py:80-150]()
### 关键参数
```python
class AutoconfigController:
def pick_committed(
candidates: list[ConfigCandidate],
zero_label_confidence_threshold: float = 0.5,
health_rank_weight: float = 1.0
) -> ConfigCandidate:
```
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `candidates` | `list[ConfigCandidate]` | 必需 | 待评估的配置候选列表 |
| `zero_label_confidence_threshold` | `float` | `0.5` | 零标签置信度阈值 |
| `health_rank_weight` | `float` | `1.0` | 健康度权重系数 |
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig_controller.py:100-120]()
## 阈值调优器
聚类决策阈值调优器（`autoconfig_cluster_threshold_tuner`）是v1.20.0引入的第三代学习记忆组件，与配对级MemoryLearner和字段级字段策略调优器并列。
### 调优流程
```mermaid
graph TD
A[聚类决策
approve/reject] --> B[收集决策反馈]
B --> C[计算精度-召回平衡]
C --> D[Otsu方法
自动阈值选择]
D --> E[tune_decision_threshold]
E --> F[生成per-dataset阈值建议]
```
### 核心函数
```python
def tune_decision_threshold(
decisions: list[ClusterDecision],
sensitivity: str = "auto"
) -> float:
```
| 敏感度 | 行为 | 适用场景 |
|--------|------|----------|
| `auto` | 自动选择最优阈值 | 通用场景 |
| `high_precision` | 提高阈值，减少误匹配 | 数据质量差 |
| `high_recall` | 降低阈值，减少漏匹配 | 召回优先 |
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig_cluster_threshold_tuner.py:1-100]()
## 负证据收集
负证据收集模块负责识别并利用明确的非匹配对来改进配置质量。
### 核心机制
当系统遇到高质量的负样本（确定不匹配的对）时，可以：
1. **更新阻塞策略**：将已知负样本的共同特征加入排除规则
2. **调整相似度阈值**：基于负样本的距离分布调整下界
3. **改进字段权重**：降低被负样本高相似度误导的字段权重
```python
class NegativeEvidenceCollector:
def register(
self,
pair: RecordPair,
reason: str # 证据来源：manual_review, ground_truth, heuristic
) -> None:
```
| 证据类型 | 说明 | 置信度 |
|----------|------|--------|
| `manual_review` | 人工确认的非匹配对 | 高 |
| `ground_truth` | 标准答案中的非匹配对 | 最高 |
| `heuristic` | 启发式规则识别的非匹配对 | 中 |
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig_negative_evidence.py:1-80]()
## 历史记录系统
历史记录模块持久化配置决策，支持增量学习和配置回溯。
### 数据模型
```python
@dataclass
class AutoconfigHistoryEntry:
dataset_id: str
timestamp: datetime
config_snapshot: dict
metrics: PerformanceMetrics
decision_reason: str
feedback: Optional[DecisionFeedback]
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `dataset_id` | `str` | 数据集标识符 |
| `timestamp` | `datetime` | 决策时间戳 |
| `config_snapshot` | `dict` | 配置快照 |
| `metrics` | `PerformanceMetrics` | 性能指标 |
| `decision_reason` | `str` | 决策依据 |
| `feedback` | `Optional[DecisionFeedback]` | 用户反馈 |
### 查询接口
```python
def query_similar(
dataset_features: DatasetFeatures,
limit: int = 5
) -> list[AutoconfigHistoryEntry]:
```
基于数据特征相似度检索历史配置，实现配置迁移。
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig_history.py:1-100]()
## 配置选项参考
### 全局开关
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `autoconfig.enabled` | `true` | 启用自动配置 |
| `autoconfig.recall_target` | `0.95` | 目标召回率 |
| `autoconfig.precision_floor` | `0.90` | 精度下界 |
### 零标签提交策略（v1.23.0+）
```yaml
autoconfig:
zero_label_commit: true # 启用零标签置信度提交
zero_label_confidence_threshold: 0.5
```
**v1.23.0变更说明**：控制器的`pick_committed`方法现在默认优先选择具有更高`-overall_confidence`的零标签配置候选，而非更高`-mass_separation`的候选，以避免精度崩塌问题。
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig.py:150-200]()
## 使用示例
### Python API
```python
from goldenmatch import GoldenMatch
# 零配置自动匹配
gm = GoldenMatch()
result = gm.dedupe("customers.csv")
# 查看自动配置决策
print(result.autoconfig_summary)
# Output:
# {
# "threshold": 0.87,
# "blocking_strategy": "qis_buckets",
# "field_weights": {"name": 0.4, "address": 0.3, ...},
# "confidence": 0.92
# }
```
### 配置调优回调
```python
from goldenmatch.core.autoconfig_cluster_threshold_tuner import tune_decision_threshold
# 手动触发阈值优化
decisions = gm.get_cluster_decisions()
optimal_threshold = tune_decision_threshold(decisions, sensitivity="auto")
gm.update_config({"decision_threshold": optimal_threshold})
```
## 版本历史
| 版本 | 更新内容 |
|------|----------|
| v1.24.0 | Chao1规模感知基数估计，启发式规则扩展，诊断工具 |
| v1.23.0 | 零标签置信度提交优化，默认优先选择高置信度配置 |
| v1.20.0 | 聚类决策阈值调优器（tune_decision_threshold） |
| v1.19.0 | 原生加速支持，自动配置与概率模型改进 |
## 常见问题
### Q: 自动配置的阈值是如何确定的？
A: 系统综合使用Otsu自动阈值选择方法、历史配置迁移和负证据反馈三重机制。对于未见过的数据集类型，优先参考相似历史配置的经验阈值。
### Q: 如何禁用自动配置并手动设置参数？
```python
gm = GoldenMatch(config={"autoconfig.enabled": False})
gm.set_thresholds(precision=0.95, recall=0.90)
```
### Q: 零标签配置是什么？
A: 指数据集中缺乏明确正样本（已确认匹配对）的场景。系统采用特殊的置信度评估策略，通过字段级一致性推断匹配可能性。
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig.py:200-250]()
[packages/python/goldenmatch/goldenmatch/core/autoconfig_controller.py:150-200]()
---
## 学习记忆系统
### 相关页面
相关主题：[自动配置系统](#autoconfig)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/python/goldenmatch/goldenmatch/core/memory/learner.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/memory/learner.py)
- [packages/python/goldenmatch/goldenmatch/core/memory/store.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/memory/store.py)
- [packages/python/goldenmatch/goldenmatch/core/memory/corrections.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/memory/corrections.py)
- [packages/python/goldenmatch/goldenmatch/core/autoconfig_golden_strategy_tuner.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig_golden_strategy_tuner.py)
- [packages/python/goldenmatch/goldenmatch/core/autoconfig_cluster_threshold_tune.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig_cluster_threshold_tune.py)
- [packages/python/goldenmatch/docs/learning-memory.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/docs/learning-memory.md)
# 学习记忆系统
## 概述
学习记忆系统（Learning Memory System）是 GoldenMatch 中的一套自适应机制，旨在通过用户反馈和自动分析持续优化实体解析的准确率。该系统从配对级别（pair-level）、字段级别（field-level）和聚类级别（cluster-level）三个维度收集决策信号，逐步构建和维护一个知识库，用于指导未来的匹配决策。
学习记忆系统的核心价值在于：
- **持续学习**：从人工审核和自动决策中提取模式，无需手动配置阈值
- **多层次优化**：覆盖从原始配对评分到最终聚类决策的全链路
- **零配置适应**：通过 `autoconfig` 系列调优器自动推断最佳参数
资料来源：[v1.20.0 Release Notes](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.20.0)
---
## 系统架构
学习记忆系统由三个核心调优器组成，它们分别工作在不同的抽象层次：
```mermaid
graph TD
A["用户反馈 / 自动决策"] --> B["配对级记忆学习器
MemoryLearner"]
A --> C["字段级策略调优器
GoldenStrategyTuner"]
A --> D["聚类级决策调优器
ClusterDecisionTuner"]
B --> E["配对级阈值
match_threshold"]
C --> F["字段级策略
field_strategy"]
D --> G["聚类级阈值
decision_threshold"]
E --> H["阻塞与评分"]
F --> I["字段级加权"]
G --> J["聚类合并决策"]
H --> K["候选配对生成"]
I --> L["配对评分"]
J --> M["最终聚类输出"]
```
### 三层调优器家族
| 调优器 | 层级 | 核心功能 | 资料来源 |
|--------|------|----------|----------|
| **MemoryLearner** | 配对级 | 学习配对级别的 approve/reject 决策，生成 pair-level auto-approve 阈值 | [v1.20.0 Release Notes](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.20.0) |
| **GoldenStrategyTuner** | 字段级 | 消费字段级别的 approve/reject 决策，推导 per-field 权重和策略 | [v1.20.0 Release Notes](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.20.0) |
| **ClusterDecisionTuner** | 聚类级 | 消费聚类级别的 approve/reject 决策，提出 per-dataset auto-approve 阈值 | [v1.20.0 Release Notes](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.20.0) |
---
## 核心组件
### 1. MemoryLearner（配对级记忆学习器）
MemoryLearner 是学习记忆系统的基础组件，负责在配对级别收集和响应决策信号。
#### 工作流程
```mermaid
graph LR
A["候选配对"] --> B["生成评分"]
B --> C["获取记忆阈值"]
C --> D{"评分 >= 阈值?"}
D -->|"是"| E["自动批准"]
D -->|"否"| F["进入审核队列"]
E --> G["记录正样本"]
F --> H{"用户决策"}
H -->|"批准"| I["更新记忆模型"]
H -->|"拒绝"| J["更新记忆模型"]
```
#### API 接口
```python
from goldenmatch.core.memory import MemoryLearner
# 初始化学习器
learner = MemoryLearner(
name="my_learner",
recall_target=0.95, # 目标召回率
)
# 注册决策
learner.approve(pair_id) # 批准配对
learner.reject(pair_id) # 拒绝配对
# 获取当前阈值
threshold = learner.get_threshold()
# 调优（基于积累的决策）
learner.tune()
```
#### 配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `recall_target` | float | 0.95 | 目标召回率 |
| `precision_weight` | float | 0.5 | 精确率权重 |
| `memory_decay` | float | 0.95 | 历史样本衰减系数 |
| `min_samples` | int | 100 | 开始调优的最小样本数 |
资料来源：[packages/python/goldenmatch/goldenmatch/core/memory/learner.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/memory/learner.py)
---
### 2. GoldenStrategyTuner（字段级策略调优器）
字段级策略调优器负责分析每个字段的匹配质量，并动态调整字段权重和策略。
#### 核心功能
- 分析每个字段在不同匹配策略下的表现
- 学习哪些字段对最终决策贡献最大
- 自动选择最佳字段策略（exact / fuzzy / token-set / common-prefix 等）
#### 配置示例
```python
from goldenmatch.core.autoconfig_golden_strategy_tuner import GoldenStrategyTuner
tuner = GoldenStrategyTuner(
dataset_id="customer_records",
field_config={
"name": {"strategy": "fuzzy", "weight": 1.5},
"email": {"strategy": "exact", "weight": 2.0},
"phone": {"strategy": "phone_e164", "weight": 1.0},
},
)
# 调优字段策略
tuner.tune(feedback_data)
```
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig_golden_strategy_tuner.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig_golden_strategy_tuner.py)
---
### 3. ClusterDecisionTuner（聚类级决策调优器）
聚类级决策调优器是学习记忆家族的第三个成员（v1.20.0引入），负责优化最终的聚类合并决策。
#### 功能特点
- 消费 cluster-level 的 approve/reject 决策
- 提出 per-dataset 的 auto-approve 阈值建议
- 通过 `tune_decision_threshold` 方法自动推断最佳决策阈值
#### API 接口
```python
from goldenmatch.core.autoconfig_cluster_threshold_tune import tune_decision_threshold
# 基于聚类级反馈调优决策阈值
recommended_threshold = tune_decision_threshold(
cluster_decisions=[
{"cluster_id": "c1", "approved": True, "confidence": 0.9},
{"cluster_id": "c2", "approved": False, "confidence": 0.7},
# ...
],
target_precision=0.99,
target_recall=0.95,
)
```
资料来源：[packages/python/goldenmatch/goldenmatch/core/autoconfig_cluster_threshold_tune.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/autoconfig_cluster_threshold_tune.py)
---
## 数据持久化
学习记忆系统的状态通过 `MemoryStore` 进行持久化，支持多种后端存储。
### MemoryStore 接口
```python
from goldenmatch.core.memory.store import MemoryStore
# 初始化存储
store = MemoryStore(backend="sqlite", path="./memory.db")
# 保存学习状态
store.save_learner_state("my_learner", learner.get_state())
# 加载学习状态
state = store.load_learner_state("my_learner")
learner.restore(state)
# 获取统计数据
stats = store.get_memory_stats("my_learner")
```
### 支持的存储后端
| 后端 | 说明 | 适用场景 |
|------|------|----------|
| `sqlite` | 本地 SQLite 数据库 | 单机部署 |
| `postgres` | PostgreSQL 数据库 | 生产环境高可用 |
| `duckdb` | DuckDB 列式存储 | 分析型工作流 |
PostgreSQL 扩展支持通过 `memory_learn` 和 `memory_stats` CRUD 操作进行数据库级记忆管理。
资料来源：[packages/python/goldenmatch/goldenmatch/core/memory/store.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/memory/store.py)
---
## 纠正机制
学习记忆系统支持对错误决策进行纠正，确保模型能够从错误中学习。
### Corrections 接口
```python
from goldenmatch.core.memory.corrections import CorrectionLog
# 记录纠正
correction = CorrectionLog()
correction.record(
original_decision={"pair_id": "p123", "decision": "approve"},
corrected_decision={"pair_id": "p123", "decision": "reject"},
reason="用户纠正：这两个记录不应匹配",
)
# 分析纠正模式
patterns = correction.analyze_patterns()
```
### 纠正类型
| 类型 | 说明 | 处理方式 |
|------|------|----------|
| `false_positive` | 错误批准 | 下调相关配对的评分权重 |
| `false_negative` | 错误拒绝 | 上调相关配对的评分权重 |
| `field_error` | 字段级错误 | 调整特定字段的策略参数 |
资料来源：[packages/python/goldenmatch/goldenmatch/core/memory/corrections.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/memory/corrections.py)
---
## 与 autoconfig 的集成
学习记忆系统与 GoldenMatch 的自动配置机制深度集成，实现零配置的持续优化。
### 自动配置流程
```mermaid
graph TD
A["初始化配置"] --> B["运行首次匹配"]
B --> C["收集初始决策"]
C --> D["触发 MemoryLearner 调优"]
D --> E["触发 GoldenStrategyTuner 调优"]
E --> F["触发 ClusterDecisionTuner 调优"]
F --> G["更新配置参数"]
G --> H["重新运行匹配"]
H --> I{"达到目标指标?"}
I -->|"否"| D
I -->|"是"| J["部署配置"]
J --> K["监控与持续学习"]
K --> L{"新反馈?"}
L -->|"是"| M["增量更新"]
M --> G
```
### 零配置自动调优
v1.23.0 引入了自动配置通过零标签置信度进行提交的机制。控制器的 `pick_committed` 决策逻辑优先选择具有更高 `-overall_confidence` 的候选者，而非具有更高 `-mass_separation` 的候选者（在具有零标签配置文件的同健康等级候选者中）。
```python
from goldenmatch import GoldenMatch
# 零配置模式 - 自动启用学习记忆
matcher = GoldenMatch(
autoconfig=True, # 启用自动配置
learning_memory=True, # 启用学习记忆
recall_target=0.95, # 目标召回率
)
```
资料来源：[v1.23.0 Release Notes](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.23.0)
---
## 配置参考
### 全局配置
```yaml
learning_memory:
enabled: true
recall_target: 0.95
precision_target: 0.99
memory_store:
backend: postgres
connection: postgresql://user:pass@host/db
tuners:
pair_level:
enabled: true
min_samples: 100
decay_factor: 0.95
field_level:
enabled: true
strategies: [exact, fuzzy, token_set, common_prefix]
cluster_level:
enabled: true
decision_metric: mass_separation
```
### 环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GOLDENMATCH_MEMORY_BACKEND` | 存储后端类型 | `sqlite` |
| `GOLDENMATCH_MEMORY_PATH` | SQLite 数据库路径 | `./goldenmatch_memory.db` |
| `GOLDENMATCH_LEARNING_ENABLED` | 启用学习记忆 | `true` |
---
## 使用示例
### 基础用法
```python
from goldenmatch import GoldenMatch
from goldenmatch.core.memory import MemoryLearner
# 创建带学习记忆的匹配器
matcher = GoldenMatch(
data=customers_df,
blocking_keys=["postal_code", "last_name_prefix"],
autoconfig=True,
)
# 运行匹配（自动学习）
result = matcher.match()
# 获取学习状态
stats = matcher.get_learning_stats()
print(f"学习的配对数: {stats['learned_pairs']}")
print(f"当前阈值: {stats['current_threshold']}")
```
### 渐进式学习
```python
# 第一批数据
batch1 = load_data("customers_2024.csv")
result1 = matcher.match(batch1)
# 第二批数据（继承学习状态）
batch2 = load_data("customers_2025.csv")
result2 = matcher.match(batch2)
# 查看学习进展
progress = matcher.get_learning_progress()
```
### 与 PostgreSQL 集成
```python
from goldenmatch.extensions.pg import GoldenMatchPG
# 使用数据库级记忆存储
matcher = GoldenMatchPG(
data=records,
memory_table="memory_learn",
stats_table="memory_stats",
)
```
---
## 最佳实践
### 1. 初始数据准备
- 确保初始数据集具有代表性，覆盖各种匹配场景
- 建议初始样本量不少于 1000 条记录
- 包含一定比例的已确认匹配/不匹配记录用于校准
### 2. 阈值设置
| 场景 | 建议 recall_target | 说明 |
|------|-------------------|------|
| 宽松匹配（高召回） | 0.98-0.99 | 适用于需要发现尽可能多匹配的用例 |
| 平衡匹配 | 0.95-0.97 | 默认推荐，适用于大多数场景 |
| 严格匹配（高精度） | 0.90-0.94 | 适用于误匹配成本较高的场景 |
### 3. 持续优化
- 定期审查纠正日志，识别系统性错误模式
- 在数据分布发生变化时重新校准阈值
- 使用 A/B 测试验证学习效果
---
## 限制与已知问题
### 当前限制
1. **冷启动问题**：初期样本不足时，调优结果可能不够稳定
2. **概念漂移**：当数据分布发生显著变化时，需要重新校准
3. **跨数据集迁移**：学习状态在数据集间迁移时需要谨慎验证
### 社区反馈
- v1.23.0 中修复了零标签配置下的精度崩溃问题，改进了 `pick_committed` 决策逻辑
- v1.24.0 通过 Chao1 规模感知基数估计改进了学习记忆的准确性
资料来源：[v1.23.0 Release Notes](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.23.0)、[v1.24.0 Release Notes](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.24.0)
---
## 相关文档
- [学习记忆文档](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/docs/learning-memory.md)
- [自动配置指南](./autoconfig.md)
- [实体解析最佳实践](./best-practices.md)
- [GoldenMatch 主文档](../README.md)
---
## Blocking 策略
### 相关页面
相关主题：[处理管道](#pipeline), [评分系统](#scoring)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/python/goldenmatch/goldenmatch/core/blocker.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/blocker.py)
- [packages/python/goldenmatch/goldenmatch/core/ann_blocker.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/ann_blocker.py)
- [packages/python/goldenmatch/goldenmatch/core/learned_blocking.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/learned_blocking.py)
- [packages/python/goldenmatch/goldenmatch/core/blocking_candidates.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/blocking_candidates.py)
- [packages/python/goldenmatch/docs/blocking.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/docs/blocking.md)
- [packages/python/goldenmatch/web/frontend/src/lib/types.ts](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/web/frontend/src/lib/types.ts)
# Blocking 策略
## 概述
Blocking 是实体解析（Entity Resolution）流程中的关键性能优化步骤。其核心目标是通过将可能匹配的记录分到同一"块"（block）中，大幅减少需要两两比较的记录对数量。在 GoldenMatch 中，未使用 blocking 时需要进行 O(n²) 的全量比较，而引入 blocking 后只需对同一 block 内的记录进行两两比较，从而将比较次数降低到可管理的规模。
GoldenMatch 支持多种 blocking 策略，包括标准 blocking、基于近似最近邻（ANN）的 blocking、以及学习型 blocking。用户可以根据数据规模、字段特征和性能需求选择合适的策略组合。
## Blocking 策略架构
```mermaid
graph TD
A[输入数据集] --> B[Blocking 策略选择]
B --> C[标准 Blocking]
B --> D[ANN Blocking]
B --> E[Learned Blocking]
C --> F[生成候选对]
D --> F
E --> F
F --> G[两两比较 & 评分]
G --> H[聚类 & 决策]
H --> I[Golden Records]
```
## Blocking 配置结构
### 前端类型定义
```typescript
// 已知 Blocking 配置字段
const BLOCKING_KNOWN_KEYS = new Set([
"block_size",
"skip_oversized",
"auto_suggest",
"auto_select",
"extras",
]);
export type BlockingPayload = {
block_size?: number;
skip_oversized?: boolean;
auto_suggest?: boolean;
auto_select?: boolean;
extras?: Record;
};
```
资料来源：[packages/python/goldenmatch/web/frontend/src/lib/types.ts:1-28]()
### 配置参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `block_size` | int | - | 每个 block 的最大记录数 |
| `skip_oversized` | bool | - | 当 block 超过阈值时是否跳过 |
| `auto_suggest` | bool | - | 是否自动建议 blocking 策略 |
| `auto_select` | bool | - | 是否自动选择最优策略 |
| `extras` | dict | - | 高级策略的额外配置参数 |
## 标准 Blocking
### 工作原理
标准 Blocking 通过一个或多个"blocking key"字段将记录分组。所有在相同 blocking key 上具有相同值的记录会被放入同一个 block，然后只在该 block 内进行两两比较。
### 配置示例
```yaml
blocking:
block_size: 5000
skip_oversized: true
strategy:
- field: last_name
standardizer: name_upper
- field: zip5
```
### 适用场景
- 数据具有明确的分类字段（如邮编、姓氏首字母、行业代码）
- 数据量在百万级别以下
- 需要精确匹配结果的场景
## ANN Blocking（近似最近邻）
### 工作原理
ANN Blocking 利用向量嵌入（embeddings）将每条记录转换为高维向量，然后使用近似最近邻算法找到与目标记录最相似的记录对。这种方法特别适合处理模糊匹配和语义相似的情况。
### 性能特征
| 指标 | 标准 Blocking | ANN Blocking |
|------|--------------|--------------|
| 召回率 | 依赖精确 key | 可调整召回率 |
| 精度 | 高 | 可调整 |
| 计算成本 | 低 | 中等 |
| 内存占用 | 低 | 较高 |
### 配置示例
```yaml
blocking:
strategy:
ann:
embedder: local
min_hash_size: 128
n_jobs: -1
```
资料来源：[packages/python/goldenmatch/goldenmatch/core/ann_blocker.py]()
## Learned Blocking（学习型 Blocking）
### 工作原理
Learned Blocking 使用机器学习模型自动学习哪些记录对最可能匹配。通过分析历史标注数据或使用主动学习策略，系统能够智能地发现最优的 blocking 策略组合。
### 核心特性
1. **自动特征选择**：从多个候选字段中选择最有效的 blocking key
2. **自适应阈值**：根据数据分布动态调整 blocking 范围
3. **多策略组合**：支持同时使用多种 blocking 策略
### 配置示例
```yaml
blocking:
strategy:
learned:
min_training_pairs: 1000
candidate_generation: aggressive
recall_target: 0.95
```
资料来源：[packages/python/goldenmatch/goldenmatch/core/learned_blocking.py]()
## Blocking 候选对生成
### 核心逻辑
```python
# blocking_candidates.py 中的核心流程
def generate_candidates(records, blocking_config):
# 1. 应用 standardization 到 blocking key 字段
# 2. 按 blocking key 分组
# 3. 生成组内所有两两组合
# 4. 应用过滤规则（如 skip_oversized）
# 5. 返回候选对列表
```
### 生成流程
```mermaid
graph LR
A[原始记录] --> B[标准化 Blocking Key]
B --> C[分组]
C --> D{Block 大小检查}
D -->|≤ 阈值| E[生成候选对]
D -->|> 阈值| F{skip_oversized?}
F -->|是| G[跳过或子采样]
F -->|否| E
E --> H[候选对输出]
```
### 性能优化
1. **Block 大小限制**：防止过大的 block 导致内存溢出
2. **子采样策略**：对超大 block 采用智能采样
3. **并行处理**：支持多核并行生成候选对
资料来源：[packages/python/goldenmatch/goldenmatch/core/blocking_candidates.py]()
## 多策略组合
### Canopy Clustering
Canopy Clustering 是一种快速的粗聚类方法，常用于 ANN Blocking 的预处理阶段：
```yaml
blocking:
strategy:
canopy:
t1: 0.8 # 宽松阈值
t2: 0.6 # 严格阈值
```
### 多 Pass Blocking
对于复杂数据集，可以组合多个 blocking 策略以提高召回率：
```yaml
blocking:
multi_pass:
- field: email
standardizer: email
- field: phone
standardizer: phone
- field: name
standardizer: name_proper
min_length: 3
```
## 性能调优
### v1.24.0 性能改进
最新版本（v1.24.0）在 blocking 性能上实现了显著提升：
| 指标 | 改进前 | 改进后 | 提升 |
|------|--------|--------|------|
| 10M 数据处理时间 | 2604s | 502s | -81% |
| 内存占用 (RSS) | - | -18% | 18% |
关键改进包括：
- Chao1 scale-aware cardinality 估算
- Heuristic rule expansion
- 诊断工具（diagnostic harness）
### 配置建议
| 数据规模 | 推荐策略 | block_size |
|----------|----------|------------|
| < 100K | 标准 Blocking | 5000 |
| 100K - 1M | 标准 + ANN | 3000 |
| 1M - 10M | ANN + Canopy | 2000 |
| > 10M | 学习型 + 多 Pass | 1000 |
## 常见问题
### Q: 如何选择 blocking key？
A: 优先选择具有以下特征的字段：
- 高基数（unique 值多）
- 低噪音（错误少）
- 与实体身份强相关
### Q: block 过大导致内存不足怎么办？
A: 设置 `skip_oversized: true`，系统会自动跳过超大型 block 或进行智能子采样。
### Q: 如何平衡召回率和性能？
A: 使用 `multi_pass` 配置多轮 blocking，每轮使用不同的策略组合，逐轮提高召回率。
## 相关文档
- [Blocking 官方文档](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/docs/blocking.md)
- [高级配置指南](../examples/advanced_config.py)
- [性能基准测试](../examples/benchmark.py)
---
## 评分系统
### 相关页面
相关主题：[处理管道](#pipeline), [Blocking 策略](#blocking), [自动配置系统](#autoconfig)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/python/goldenmatch/goldenmatch/core/scorer.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/scorer.py)
- [packages/python/goldenmatch/goldenmatch/core/cross_encoder.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/cross_encoder.py)
- [packages/python/goldenmatch/goldenmatch/core/probabilistic.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/probabilistic.py)
- [packages/python/goldenmatch/goldenmatch/core/llm_scorer.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/llm_scorer.py)
- [packages/python/goldenmatch/goldenmatch/core/embedder.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/embedder.py)
- [packages/python/goldenmatch/goldenmatch/core/zero_label_confidence.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/core/zero_label_confidence.py)
# 评分系统
GoldenMatch 的评分系统是实体解析引擎的核心组件，负责量化两条记录之间的相似程度。该系统支持多种评分策略，包括模糊匹配、概率模型、LLM 增强评分和语义嵌入评分，并通过零标签置信度机制实现自动配置优化。
## 系统架构概述
评分系统在实体解析流程中扮演关键角色，接收候选记录对并输出相似度分数，驱动后续的聚类和决策过程。
```mermaid
graph TD
A[候选记录对] --> B[字段级评分]
B --> C[聚合评分]
C --> D{评分策略选择}
D -->|概率模型| E[Fellegi-Sunter]
D -->|LLM增强| F[LLM Scorer]
D -->|语义相似| G[Embedder]
D -->|零标签| H[Zero Label Confidence]
E --> I[综合分数]
F --> I
G --> I
H --> I
I --> J[决策阈值]
J --> K[匹配/非匹配]
```
## 核心评分器 (Scorer)
`scorer.py` 是评分系统的基础模块，实现了字段级别和记录级别的评分逻辑。
### 主要职责
| 职责 | 说明 |
|------|------|
| 字段相似度计算 | 支持字符串编辑距离、Jaccard、精确匹配等多种算法 |
| 权重分配 | 根据字段重要性进行加权聚合 |
| Matchkey 评分 | 针对特定匹配键的评分策略 |
| 配置驱动 | 通过 `FieldStrategy` 配置灵活选择评分方法 |
### 评分方法映射
| 配置字段 | 评分方法 | 适用场景 |
|----------|----------|----------|
| `jaro_winkler` | Jaro-Winkler 相似度 | 字符串相似度，容忍轻微拼写错误 |
| `levenshtein` | 编辑距离归一化 | 精确衡量字符差异 |
| `jaccard` | Jaccard 集合相似度 | 分词后的词汇匹配 |
| `exact` | 精确相等 | 唯一标识符或结构化字段 |
资料来源：[scorer.py](packages/python/goldenmatch/goldenmatch/core/scorer.py)
### 评分配置示例
```python
from goldenmatch import GoldenMatchConfig, FieldStrategy
config = GoldenMatchConfig(
match_fields=[
{"name": "email", "strategy": "jaro_winkler", "weight": 0.4},
{"name": "name", "strategy": "jaccard", "weight": 0.3},
{"name": "phone", "strategy": "exact", "weight": 0.3}
]
)
```
## 交叉编码器评分 (Cross Encoder)
`cross_encoder.py` 提供了基于预训练语言模型的细粒度评分能力，能够理解语义上下文。
### 工作原理
交叉编码器将两条记录拼接后一次性输入模型，直接预测匹配概率，而非像双塔模型那样分别编码。
```mermaid
graph LR
A[Record A] -->|拼接| C[Cross Encoder]
B[Record B] -->|拼接| C
C -->|端到端推理| D[匹配概率]
```
### 支持的模型后端
| 后端 | 模型示例 | 特点 |
|------|----------|------|
| `transformers` | `cross-encoder/ms-marco` | 高精度，GPU 推荐 |
| `sentence-transformers` | `cross-encoder/quora-roberta-base` | 语义理解强 |
| `onnx` | 量化后的交叉编码器 | CPU 高效推理 |
### 配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_name` | `str` | `cross-encoder/ms-marco-MiniLM-L-6-v2` | 交叉编码器模型 |
| `batch_size` | `int` | `32` | 批处理大小 |
| `device` | `str` | `auto` | 计算设备选择 |
| `max_length` | `int` | `512` | 输入最大长度 |
资料来源：[cross_encoder.py](packages/python/goldenmatch/goldenmatch/core/cross_encoder.py)
## 概率评分模型 (Probabilistic)
`probabilistic.py` 实现了 Fellegi-Sunter 概率框架，这是实体解析领域的经典方法。
### Fellegi-Sunter 模型
该模型基于贝叶斯概率论，将匹配过程形式化为：
$$P(\text{match} | \gamma) = \frac{m_\gamma \cdot \lambda}{m_\gamma \cdot \lambda + u_\gamma \cdot (1-\lambda)}$$
其中：
- $m_\gamma$：在 match 条件下观察到字段比较向量 $\gamma$ 的概率
- $u_\gamma$：在 non-match 条件下观察到 $\gamma$ 的概率
- $\lambda$：先验匹配概率
### EM 参数估计
```python
from goldenmatch.core.probabilistic import train_em, score_probabilistic
# 训练 m/u 概率
em_result = train_em(
labeled_pairs=labeled_data,
matchkeys=["name_jw", "phone_exact"],
max_iterations=100,
convergence_threshold=1e-5
)
# 对候选对评分
scores = score_probabilistic(
candidate_pairs=candidates,
matchkeys=["name_jw", "phone_exact"],
em_result=em_result
)
```
### 训练参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `max_iterations` | `int` | `100` | EM 算法最大迭代次数 |
| `convergence_threshold` | `float` | `1e-6` | 收敛阈值 |
| `initial_m` | `dict` | `None` | m 概率初始值 |
| `initial_u` | `dict` | `None` | u 概率初始值 |
资料来源：[probabilistic.py](packages/python/goldenmatch/goldenmatch/core/probabilistic.py)
## LLM 评分 (LLM Scorer)
`llm_scorer.py` 利用大型语言模型进行零样本评分，特别适用于结构化数据和复杂语义场景。
### 支持的 LLM 提供商
| 提供商 | 模型 | 认证方式 |
|--------|------|----------|
| OpenAI | `gpt-4`, `gpt-3.5-turbo` | `OPENAI_API_KEY` |
| Anthropic | `claude-3-opus`, `claude-3-sonnet` | `ANTHROPIC_API_KEY` |
| 本地模型 | Ollama 支持的模型 | `OLLAMA_BASE_URL` |
### 评分提示词模板
```python
from goldenmatch.core.llm_scorer import LLMScorer
scorer = LLMScorer(
provider="openai",
model="gpt-4",
prompt_template="""判断以下两条记录是否匹配：
记录A: {record_a}
记录B: {record_b}
返回 JSON: {"match": true/false, "confidence": 0.0-1.0, "reason": "..."}"""
)
result = scorer.score(record_a, record_b)
```
### 与传统评分融合
```mermaid
graph TD
A[候选对] --> B[传统评分]
A --> C[LLM 评分]
B --> D[加权融合]
C --> D
D --> E[最终分数]
```
资料来源：[llm_scorer.py](packages/python/goldenmatch/goldenmatch/core/llm_scorer.py)
## 语义嵌入评分 (Embedder)
`embedder.py` 提供了语义向量表示能力，适用于需要理解文本含义的场景。
### 嵌入策略
| 策略 | 说明 | 适用场景 |
|------|------|----------|
| `average` | 字段 token 平均 | 短文本 |
| `cls_token` | 使用 [CLS] 向量 | BERT 系列模型 |
| `max_pooling` | 最大池化 | 强调关键特征 |
| `weighted` | 加权聚合 | 多字段组合 |
### 本地嵌入器栈
v1.19.0 引入了本地/自托管嵌入器支持：
```python
from goldenmatch.core.embedder import LocalEmbedder
embedder = LocalEmbedder(
model="sentence-transformers/all-MiniLM-L6-v2",
device="cuda",
batch_size=128
)
vectors = embedder.encode(records, field="description")
similarity = embedder.cosine_similarity(vectors_a, vectors_b)
```
资料来源：[embedder.py](packages/python/goldenmatch/goldenmatch/core/embedder.py)
## 零标签置信度 (Zero Label Confidence)
`zero_label_confidence.py` 实现了无标注数据下的自动置信度校准机制，是 v1.23.0 的核心特性。
### 核心概念
零标签置信度通过分析匹配分布的统计特性，自动推断最优决策阈值，无需人工标注数据。
```mermaid
graph TD
A[候选对分数分布] --> B[双峰检测]
B --> C{是否为双峰?}
C -->|是| D[质量分离度量]
C -->|否| E[单峰分析]
D --> F[Otsu 阈值估计]
E --> G[保守阈值]
F --> H[置信度分数]
G --> H
```
### 质量分离度量 (Mass Separation)
```python
from goldenmatch.core.zero_label_confidence import compute_zero_label_confidence
confidence = compute_zero_label_confidence(
pair_scores=all_scores,
health_rank_by_group=group_health,
pick_by="overall_confidence" # v1.23.0 默认
)
```
### 控制器集成
v1.23.0 更新了 `pick_committed` 逻辑：当多个候选具有相同健康等级时，优先选择 `overall_confidence` 更高的候选，而非 `mass_separation` 更高的候选。这有效避免了精度塌陷问题。
| 配置选项 | 说明 |
|----------|------|
| `zero_label_confidence_enabled` | 启用零标签置信度 |
| `zero_label_pick_by` | 候选选择策略 |
| `precision_collapse_threshold` | 精度塌陷警戒线 |
资料来源：[zero_label_confidence.py](packages/python/goldenmatch/goldenmatch/core/zero_label_confidence.py)
## 评分融合策略
GoldenMatch 支持多种评分融合方式，以适应不同数据特征。
### 融合方法
| 方法 | 公式 | 特点 |
|------|------|------|
| 加权平均 | $\sum w_i \cdot s_i$ | 简单直观 |
| 几何平均 | $(\prod s_i)^{1/n}$ | 惩罚极端低分 |
| 最小值 | $\min(s_i)$ | 保守策略 |
| 最大值 | $\max(s_i)$ | 激进策略 |
### 配置示例
```python
config = GoldenMatchConfig(
fusion_method="weighted",
fusion_weights={
"fuzzy": 0.4,
"probabilistic": 0.3,
"llm": 0.2,
"embedding": 0.1
},
decision_threshold=0.85 # 自动调优或手动设置
)
```
## 性能优化
### v1.24.0 性能改进
最新版本在评分系统层面进行了多项优化：
- **QIS-bucket-realistic 基准**：10M 记录处理时间从 2604s 降至 502s（-81%）
- **内存优化**：RSS 减少 18%，得益于 Chao1 基数估计
- **启发式规则扩展**：减少不必要的评分计算
### 加速策略
| 策略 | 适用场景 | 加速比 |
|------|----------|--------|
| 预过滤 (Blocking) | 大规模数据 | 10x-100x |
| 批处理评分 | GPU 利用 | 5x-20x |
| 量化模型 | CPU 部署 | 2x-4x |
| 近似最近邻 | 嵌入搜索 | 100x+ |
## 最佳实践
### 评分策略选择指南
```mermaid
graph TD
A[数据特点] --> B{是否有标注数据?}
B -->|是| C{数据量?}
B -->|否| D{精度要求?}
C -->|大规模| E[Probabilistic + Fuzzy]
C -->|小规模| F[LLM + Fuzzy]
D -->|高| G[Probabilistic + LLM]
D -->|一般| H[Zero Label + Fuzzy]
```
### 常见问题
**Q：如何选择评分阈值？**
A：GoldenMatch 提供三种方式：
1. 手动设置 `decision_threshold`
2. 使用 `tune_decision_threshold()` 基于标注数据调优
3. 启用零标签置信度自动推断（v1.23.0+）
**Q：LLM 评分成本过高怎么办？**
A：建议采用分层策略：
1. 用快速评分（fuzzy/embedding）过滤掉明显不匹配的对
2. 仅对边界案例调用 LLM 评分
**Q：如何处理高精度场景？**
A：参考 v1.23.0 的精度塌陷防护机制，优先使用 `overall_confidence` 而非 `mass_separation` 作为零标签场景的最终排序依据。
---
## 数据库集成
### 相关页面
相关主题：[SQL 扩展](#sql-extensions)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/python/goldenmatch/goldenmatch/connectors/postgres.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/connectors/postgres.py)
- [packages/python/goldenmatch/goldenmatch/connectors/mongo.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/connectors/mongo.py)
- [packages/python/goldenmatch/goldenmatch/connectors/snowflake.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/connectors/snowflake.py)
- [packages/python/goldenmatch/goldenmatch/db/sync.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/db/sync.py)
- [packages/python/goldenmatch/goldenmatch/db/connector.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/goldenmatch/db/connector.py)
- [packages/rust/extensions/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/rust/extensions/README.md)
# 数据库集成
## 概述
GoldenMatch 提供全面的数据库集成支持，允许用户直接对存储在企业数据库中的数据进行实体解析和去重处理。数据库集成模块使 GoldenMatch 能够从多种数据源读取数据，并将匹配结果写回数据库或生成可直接导入数据库的输出文件。
该集成层支持 PostgreSQL、MongoDB、Snowflake 等主流数据库，并提供 Rust 扩展（`goldenmatch_pg`）实现 SQL 原生模糊匹配。通过统一的连接器架构，用户可以使用相同的配置模式对接不同的数据库，无需编写定制化代码。资料来源：[packages/python/goldenmatch/goldenmatch/db/connector.py:1-50]()
## 架构设计
### 连接器架构
GoldenMatch 的数据库集成采用插件式连接器架构，核心组件包括：
| 组件 | 职责 | 文件位置 |
|------|------|----------|
| `DBConnector` | 基类定义统一的连接器接口 | `goldenmatch/db/connector.py` |
| `PostgresConnector` | PostgreSQL 数据库连接与查询 | `goldenmatch/connectors/postgres.py` |
| `MongoConnector` | MongoDB 文档数据库连接 | `goldenmatch/connectors/mongo.py` |
| `SnowflakeConnector` | Snowflake 云数据仓库连接 | `goldenmatch/connectors/snowflake.py` |
| `DBSync` | 数据库同步与批处理写入 | `goldenmatch/db/sync.py` |
```mermaid
graph TD
A[用户配置] --> B[DBConnector 基类]
B --> C[PostgresConnector]
B --> D[MongoConnector]
B --> E[SnowflakeConnector]
F[goldenmatch_pg 扩展] --> G[PostgreSQL 原生 UDF]
H[DuckDB UDF] --> I[Rust 内核]
C --> G
E --> I
```
### 连接器基类接口
所有数据库连接器继承自 `DBConnector` 基类，实现以下核心方法：
```python
class DBConnector(Protocol):
def connect(self, config: dict) -> Connection: ...
def read_table(self, table: str, columns: list[str], filters: dict) -> DataFrame: ...
def write_results(self, results: DataFrame, target: str, mode: str) -> int: ...
def health_check(self) -> bool: ...
```
资料来源：[packages/python/goldenmatch/goldenmatch/db/connector.py:15-45]()
## 支持的数据库
### PostgreSQL
PostgreSQL 是 GoldenMatch 数据库集成的核心支持目标，提供两种集成方式：
#### Python 连接器
标准 Python 连接器支持：
- 连接池管理
- 增量读取（支持游标分页）
- 批量写入
- 事务支持
```python
from goldenmatch.connectors.postgres import PostgresConnector
connector = PostgresConnector(
host="db.example.com",
port=5432,
database="customers",
user="readonly_user",
password="${DB_PASSWORD}", # 支持环境变量
ssl_mode="require"
)
# 读取客户表
df = connector.read_table(
table="customers",
columns=["customer_id", "name", "email", "phone"],
filters={"status": "active"}
)
# 执行匹配
results = goldenmatch.dedupe(df, config="match_config.yml")
# 写回匹配结果
connector.write_results(results, "match_results", mode="overwrite")
```
资料来源：[packages/python/goldenmatch/goldenmatch/connectors/postgres.py:1-80]()
#### Rust 扩展 (goldenmatch_pg)
`goldenmatch_pg` 是 goldenmatch 的 PostgreSQL 扩展（pgrx），提供 13 个原生 SQL 函数：
| 函数名 | 功能 | 用法示例 |
|--------|------|----------|
| `gm_dedupe` | 基础去重 | `SELECT gm_dedupe('customers', 'id')` |
| `gm_match_pairs` | 配对匹配 | `SELECT gm_match_pairs('table1', 'table2')` |
| `gm_block` | 分块过滤 | `SELECT gm_block USING (soundex(name))` |
| `gm_score` | 相似度评分 | `SELECT gm_score(name1, name2)` |
| `gm_goldenflow_*` | 数据标准化 | `SELECT gm_goldenflow_normalize_phone(phone)` |
| `memory_learn` | 学习记忆存储 | CRUD 操作 |
| `memory_stats` | 统计信息存储 | 查询历史匹配统计 |
v0.5.0 版本特性：
- 核心 API 完全兼容
- `goldenflow_*` 数据转换函数
- `memory_learn` / `memory_stats` CRUD 操作
- SQL 原生调用，无需数据迁移
安装方式：
```bash
# 编译安装（需要 Rust 工具链）
cargo install --git https://github.com/benseverndev-oss/goldenmatch --package goldenmatch_pg
# 或使用预编译版本
pip install goldenmatch[native]
```
资料来源：[packages/rust/extensions/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/rust/extensions/README.md)
### MongoDB
MongoDB 连接器支持文档型数据库的实体解析：
```python
from goldenmatch.connectors.mongo import MongoConnector
connector = MongoConnector(
uri="mongodb://mongo.example.com:27017",
database="customer_db",
collection="customers",
read_preference="secondaryPreferred" # 从副本集从节点读取
)
# 读取文档，支持聚合管道过滤
df = connector.read_collection(
pipeline=[
{"$match": {"status": "active"}},
{"$project": {"_id": 1, "name": 1, "email": 1}}
]
)
```
关键特性：
- 支持 MongoDB 聚合管道作为过滤器
- 副本集读取偏好配置
- 文档 ID 到关系型 ID 的映射
- 嵌套字段访问支持
资料来源：[packages/python/goldenmatch/goldenmatch/connectors/mongo.py:1-60]()
### Snowflake
Snowflake 连接器支持云数据仓库场景：
```python
from goldenmatch.connectors.snowflake import SnowflakeConnector
connector = SnowflakeConnector(
account="xy12345.us-east-1",
user="etl_user",
password="${SNOWFLAKE_PASSWORD}",
warehouse="COMPUTE_WH",
database="CUSTOMER_DB",
schema="PUBLIC"
)
# 读取大型表（自动分块）
df = connector.read_table(
table="CUSTOMER_RECORDS",
columns=["C_ID", "NAME", "EMAIL", "PHONE"],
chunk_size=100000 # 分块读取，避免内存溢出
)
```
性能优化：
- 分块读取支持（`chunk_size` 参数）
- 仓库自动缩放配合
- 半结构化数据（VARIANT 列）处理
- 跨区域查询支持
资料来源：[packages/python/goldenmatch/goldenmatch/connectors/snowflake.py:1-70]()
## 配置指南
### 配置文件格式
数据库连接配置支持 YAML 格式：
```yaml
database:
type: postgres # postgres | mongodb | snowflake | duckdb
# PostgreSQL 配置
postgres:
host: localhost
port: 5432
database: customers
user: goldenmatch
password_env: DB_PASSWORD # 从环境变量读取
ssl_mode: prefer
pool_size: 5
# MongoDB 配置
mongodb:
uri: mongodb://localhost:27017
database: customers
collection: records
read_preference: secondaryPreferred
# Snowflake 配置
snowflake:
account: xy12345.us-east-1
user: user
password_env: SNOWFLAKE_PASSWORD
warehouse: COMPUTE_WH
database: DB
schema: PUBLIC
output:
type: postgres
target_table: match_results
write_mode: append # append | overwrite | upsert
upsert_key: match_id
```
### 环境变量
敏感信息通过环境变量管理：
| 环境变量 | 用途 | 示例 |
|----------|------|------|
| `DB_PASSWORD` | 数据库密码 | `export DB_PASSWORD=secret123` |
| `SNOWFLAKE_PASSWORD` | Snowflake 密码 | `export SNOWFLAKE_PASSWORD=...` |
| `MONGO_PASSWORD` | MongoDB 密码 | `export MONGO_PASSWORD=...` |
| `AWS_ACCESS_KEY_ID` | AWS 访问密钥 | S3 阶段表使用 |
| `AWS_SECRET_ACCESS_KEY` | AWS 密钥 | S3 阶段表使用 |
## 数据库同步
### DBSync 模块
`DBSync` 模块负责将匹配结果高效写入数据库：
```python
from goldenmatch.db.sync import DBSync
sync = DBSync(
connector=connector,
batch_size=5000,
retry_attempts=3,
on_conflict="ignore" # ignore | overwrite | fail
)
# 批量写入匹配结果
written = sync.write_matches(
results=match_results,
target_table="golden_records",
conflict_key="record_id"
)
```
同步策略：
| 策略 | 描述 | 适用场景 |
|------|------|----------|
| `append` | 追加写入 | 结果表为空或需保留历史 |
| `overwrite` | 覆盖写入 | 全量重新计算时使用 |
| `upsert` | 存在则更新 | 增量匹配结果写入 |
资料来源：[packages/python/goldenmatch/goldenmatch/db/sync.py:1-100]()
## 性能优化
### 大规模数据处理
处理大规模数据时的最佳实践：
```python
# 分块读取避免内存溢出
connector = PostgresConnector(config)
for chunk in connector.read_table_chunked(
table="large_table",
chunk_size=100000
):
results = goldenmatch.dedupe(chunk)
sync.write_matches(results)
# 使用数据库端过滤减少传输
df = connector.read_table(
table="customers",
filters={"updated_at": {"gt": last_sync_time}}
)
```
### 并行处理
```python
from concurrent.futures import ThreadPoolExecutor
with ThreadPoolExecutor(max_workers=4) as executor:
futures = [
executor.submit(process_chunk, chunk)
for chunk in connector.read_table_chunked("customers")
]
results = pd.concat([f.result() for f in futures])
```
## 故障排除
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 连接超时 | 网络隔离、防火墙 | 检查 `connect_timeout` 配置 |
| 内存溢出 | 读取数据过大 | 使用分块读取 `chunk_size` |
| 写入冲突 | 主键重复 | 使用 `upsert` 模式 |
| SSL 错误 | 证书验证失败 | 设置 `ssl_mode: prefer` 或提供证书 |
### 连接诊断
```python
from goldenmatch.connectors.postgres import PostgresConnector
connector = PostgresConnector(config)
# 健康检查
if not connector.health_check():
print("连接失败，检查配置")
# 测试查询
test_df = connector.read_table(
table="pg_catalog.pg_tables",
limit=5
)
```
## 相关资源
- [GoldenMatch 主文档](../goldenmatch/README.md)
- [Rust 扩展文档](../rust/extensions/README.md)
- [GoldenPipe 编排管道](../goldenpipe/README.md)
- [v1.24.0 性能优化说明](https://github.com/benseverndev-oss/goldenmatch/releases/tag/v1.24.0)
---
## SQL 扩展
### 相关页面
相关主题：[数据库集成](#database-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/rust/extensions/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/rust/extensions/README.md)
- [packages/rust/extensions/postgres/src/core_apis.rs](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/rust/extensions/postgres/src/core_apis.rs)
- [packages/rust/extensions/duckdb/goldenmatch_duckdb/core_apis.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/rust/extensions/duckdb/goldenmatch_duckdb/core_apis.py)
- [packages/python/goldenmatch/dbt-goldensuite/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/dbt-goldensuite/README.md)
- [packages/python/goldenmatch/docs/sql-postgres.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/docs/sql-postgres.md)
- [packages/python/goldenmatch/docs/sql-duckdb.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/docs/sql-duckdb.md)
# SQL 扩展
Golden Suite 提供了一套完整的 SQL 原生扩展，使实体解析、数据质量检查和数据转换功能可以直接在数据库引擎内部执行，无需数据迁移到外部工具处理。
## 概览
Golden Suite 的 SQL 扩展包括两个核心实现：
| 数据库 | 扩展包 | 实现方式 | 状态 |
|--------|--------|----------|------|
| PostgreSQL | `goldenmatch_pg` | pgrx (Rust) | v0.5.0 - 13个SQL函数 |
| DuckDB | `goldenmatch-duckdb` | Python UDF | 完整支持 |
| Snowflake | `goldenmatch` + Snowflake Cortex | SQL函数 | 完整支持 |
资料来源：[packages/rust/extensions/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/rust/extensions/README.md)
## 架构设计
```mermaid
graph TD
subgraph "客户端层"
CLI[CLI工具]
Python[Python SDK]
dbt[dbt 模型]
end
subgraph "SQL扩展层"
PG[PostgreSQL Extension
goldenmatch_pg]
DK[DuckDB UDF
goldenmatch-duckdb]
SF[Snowflake Cortex
Snowpark UDFs]
end
subgraph "核心引擎"
CM[Core Matching]
CF[Core Functions]
end
CLI --> PG
CLI --> DK
Python --> PG
Python --> DK
dbt --> PG
dbt --> DK
dbt --> SF
PG --> CM
DK --> CM
SF --> CM
PG --> CF
DK --> CF
```
## PostgreSQL 扩展 (goldenmatch_pg)
### 安装方式
```bash
# 从源码构建
cd packages/rust/extensions/postgres
cargo pgrx install --release
```
### 核心API函数
PostgreSQL 扩展通过 pgrx 框架暴露了 13 个核心 SQL 函数：
| 函数名 | 对应Python API | 功能描述 |
|--------|---------------|----------|
| `goldenmatch_dedupe(table, config_json)` | `dedupe` | 主去重函数 |
| `goldenmatch_score_pairs(pairs_json, config_json)` | `score_pairs` | 批量评分 |
| `goldenmatch_build_golden_records(clusters_json)` | `build_golden_records` | 构建黄金记录 |
| `goldenmatch_preflight(table, config_json)` | `preflight` | 预检配置 |
| `goldenmatch_postflight(table, config_json)` | `postflight` | 后置信号报告 |
| `goldenmatch_train_em(rows_json, matchkey_json, params_json)` | `train_em` | 训练EM模型 |
| `goldenmatch_score_probabilistic(rows_json, matchkey_json, em_result_json)` | `score_probabilistic` | 概率评分 |
| `goldenmatch_suggest_threshold(scores_json)` | `suggest_threshold` | 阈值建议 |
| `goldenmatch_detect_domain(columns_json)` | `detect_domain` | 领域检测 |
| `goldenmatch_validate_table(table, rules_json)` | `validate_dataframe` | 数据验证 |
| `goldenmatch_autofix_table(table)` | `auto_fix_dataframe` | 自动修复 |
| `goldenmatch_detect_anomalies(table, sensitivity)` | `detect_anomalies` | 异常检测 |
| `goldenmatch_evaluate(pairs_json, ground_truth_json)` | `evaluate_pairs/evaluate_clusters` | 评估精度 |
资料来源：[packages/rust/extensions/postgres/src/core_apis.rs](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/rust/extensions/postgres/src/core_apis.rs)
### 管道函数
除了核心API，还提供了一组管道函数用于端到端处理：
```sql
-- 执行完整去重管道
SELECT * FROM goldenmatch_dedupe('my_table', '{"blocking": {"type": "qgram", "fields": ["name", "address"]}}');
-- 预检数据质量
SELECT * FROM goldenmatch_preflight('customers', '{"checks": ["encoding", "unicode"]}');
```
### 身份图谱函数
`goldenmatch_pg` 还包含身份图谱管理函数，支持图的构建和查询：
```sql
-- 构建身份图
SELECT goldenmatch_build_graph('my_table', 'id_column');
-- 查询关联记录
SELECT * FROM goldenmatch_find_connected('graph_name', seed_record_id);
```
## DuckDB 扩展 (goldenmatch-duckdb)
### 安装方式
```bash
pip install goldenmatch-duckdb
```
### DuckDB UDF 函数
| 函数名 | 参数 | 返回值 |
|--------|------|--------|
| `goldenmatch_suggest_threshold(scores_list)` | FLOAT[] | 建议阈值 |
| `goldenmatch_detect_domain(columns_list)` | VARCHAR[] | 检测到的领域类型 |
| `goldenmatch_score_pairs(pairs_json, config_json)` | JSON | 配对评分结果 |
| `goldenmatch_build_golden_records(clusters_json)` | JSON | 黄金记录 |
| `goldenmatch_evaluate(pairs_json, ground_truth_json)` | JSON | 评估指标 |
| `goldenmatch_compare_clusters(a_json, b_json)` | JSON | 聚类比较 |
| `goldenmatch_validate_table(table, rules_json)` | JSON | 验证报告 |
| `goldenmatch_autofix_table(table)` | JSON | 修复结果 |
| `goldenmatch_detect_anomalies(table, sensitivity)` | JSON | 异常列表 |
| `goldenmatch_preflight(table, config_json)` | JSON | 预检发现 |
| `goldenmatch_postflight(table, config_json)` | JSON | 后置信号 |
| `goldenmatch_train_em(rows_json, matchkey_json, params_json)` | JSON | EM训练结果 |
| `goldenmatch_score_probabilistic(rows_json, matchkey_json, em_result_json)` | JSON | 概率分数 |
资料来源：[packages/rust/extensions/duckdb/goldenmatch_duckdb/core_apis.py](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/rust/extensions/duckdb/goldenmatch_duckdb/core_apis.py)
### 使用示例
```python
import duckdb
con = duckdb.connect()
con.sql("LOAD goldenmatch_duckdb")
# Otsu阈值建议
result = con.sql("SELECT goldenmatch_suggest_threshold('[0.1,0.12,0.9,0.92]')").fetchone()
# 异常检测
anomalies = con.sql("SELECT goldenmatch_detect_anomalies('customers', 'medium')").fetchone()
```
## Snowflake 集成
### Snowflake Cortex 函数
Golden Suite 与 Snowflake Cortex 深度集成，提供以下 SQL 函数：
| 函数名 | 功能描述 |
|--------|----------|
| `cortex_embed_768` | 768维嵌入向量生成 |
| `cortex_embed_1024` | 1024维嵌入向量生成 |
| `cortex_embed(dim)` | 维度分派的嵌入生成 |
| `cortex_cosine_similarity` | 余弦相似度计算 |
| `cortex_l2_distance` | L2距离计算 |
| `cortex_inner_product` | 内积计算 |
| `cortex_complete` | LLM完整补全 |
资料来源：[packages/python/goldenmatch/dbt-goldensuite/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/dbt-goldensuite/README.md)
### 与dbt的集成
在 Snowflake 环境下，`goldenmatch_dedupe` 支持所有三种输出模式：
```sql
-- 输出黄金记录
SELECT * FROM goldenmatch_dedupe('customers', 'golden');
-- 输出聚类
SELECT * FROM goldenmatch_dedupe('customers', 'clusters');
-- 输出配对
SELECT * FROM goldenmatch_dedupe('customers', 'pairs');
```
## dbt-goldensuite 适配器支持
### 适配器覆盖矩阵
| 适配器 | 状态 | 配置要求 |
|--------|------|----------|
| PostgreSQL | 完整支持 - 11个SQL函数 + 5个管道函数 | 安装 `goldenmatch_pg` |
| DuckDB | 完整支持 - 7个UDF + 5个身份图函数 | `pip install goldenmatch-duckdb` |
| Snowflake | 完整支持 - 与Python API表面一致 | 需要 Snowflake Cortex |
资料来源：[packages/python/goldenmatch/dbt-goldensuite/README.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/dbt-goldensuite/README.md)
### dbt宏封装
dbt-goldensuite 为每个 SQL 函数提供了便捷的宏封装：
```sql
{# 运行实体解析 #}
{{ goldenmatch_dedupe('customers', config_dict) }}
{# 评估结果 #}
{{ goldenmatch_evaluate(pairs, ground_truth) }}
{# 黄金记录构建 #}
{{ goldenmatch_build_golden_records(clusters) }}
```
## 核心配置参数
### 阻塞配置 (Blocking)
```json
{
"blocking": {
"type": "qgram",
"fields": ["name", "address"],
"ngram_size": 3,
"min_ngram_hits": 1
}
}
```
### 评分配置 (Scoring)
```json
{
"scoring": {
"fields": [
{"name": "name", "weight": 0.4, "strategy": "jaro_winkler"},
{"name": "address", "weight": 0.3, "strategy": "token_set"},
{"name": "phone", "weight": 0.3, "strategy": "numeric"}
]
}
}
```
### EM概率模型配置
```json
{
"probabilistic": {
"m_probabilities": {
"name": [0.1, 0.9],
"address": [0.15, 0.85]
},
"u_probabilities": {
"name": [0.95, 0.05],
"address": [0.9, 0.1]
}
}
}
```
资料来源：[packages/python/goldenmatch/docs/sql-postgres.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/docs/sql-postgres.md)
## 性能优化
### 向量化执行
所有 SQL 扩展均采用向量化执行模式，在 PostgreSQL 和 DuckDB 中利用列式存储特性实现高吞吐处理：
```mermaid
graph LR
A[输入数据] --> B{批量处理}
B --> C[列式向量化]
C --> D[SIMD加速]
D --> E[结果输出]
```
### 内存管理
| 数据规模 | 推荐配置 | 预期性能 |
|----------|----------|----------|
| < 100K 记录 | 默认配置 | < 10秒 |
| 100K - 1M | 增加 work_mem | < 1分钟 |
| 1M - 10M | 使用 bucket 后端 | < 10分钟 |
| > 10M | 分区处理 | 视分区数而定 |
## 版本历史
| 版本 | 发布内容 |
|------|----------|
| v0.5.0 | 核心API完全对齐 - 13个pgrx函数，goldenflow_*转换，memory_learn/memory_stats CRUD |
| v0.4.0 | 添加身份图谱函数支持 |
| v0.3.0 | Snowflake Cortex集成 |
| v0.2.0 | DuckDB UDF完整支持 |
| v0.1.0 | 初始版本 - PostgreSQL扩展 |
## 与Python SDK的对比
| 特性 | Python SDK | SQL扩展 |
|------|------------|---------|
| 部署复杂度 | 中等 | 低 |
| 数据移动 | 需要ETL | 无数据移动 |
| 性能 | 依赖数据导出 | 原生执行 |
| 灵活性 | 高 | 中等 |
| 与dbt集成 | 需要外部调用 | 原生支持 |
| 调试体验 | 完善 | 需查看数据库日志 |
资料来源：[packages/python/goldenmatch/docs/sql-duckdb.md](https://github.com/benseverndev-oss/goldenmatch/blob/main/packages/python/goldenmatch/docs/sql-duckdb.md)
## 常见问题
### Q: 如何选择 PostgreSQL 还是 DuckDB？
PostgreSQL 适合生产环境和持久化数据存储场景；DuckDB 适合分析场景和本地快速原型开发。
### Q: SQL扩展是否支持所有Python SDK的功能？
核心功能完全对齐，但部分高级配置选项可能需要通过JSON配置参数传递。
### Q: 如何调试SQL扩展的执行？
可以通过 `goldenmatch_preflight` 函数预检配置，通过 `goldenmatch_postflight` 查看执行信号。
---
---
## Doramagic 踩坑日志
项目：benseverndev-oss/goldenmatch
摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。
## 1. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1183640892 | https://github.com/benseverndev-oss/goldenmatch | README/documentation is current enough for a first validation pass.
## 2. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1183640892 | https://github.com/benseverndev-oss/goldenmatch | last_activity_observed missing
## 3. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1183640892 | https://github.com/benseverndev-oss/goldenmatch | no_demo; severity=medium
## 4. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1183640892 | https://github.com/benseverndev-oss/goldenmatch | no_demo; severity=medium
## 5. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1183640892 | https://github.com/benseverndev-oss/goldenmatch | issue_or_pr_quality=unknown
## 6. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1183640892 | https://github.com/benseverndev-oss/goldenmatch | release_recency=unknown