GoldenMatch

> **v3.22.0：零配置人员去重速度提升 18–30 倍，记录也会按输入时的原样返回。** 25 万行数据的处理时间从 520 秒缩短到 18 秒，聚类结果完全一致（升级会拉取 `goldenmatch-native` 0.2.3）。现在，唯一记录、重复记录和去重后的表格都会保留原始值，而非标准化后的值；设置 `keep_original_values=False` 或使用 `--standardized-values` 可恢复旧版输出。 > > **v3.21.0：小文件不再误报，也不会调用你未要求的 LLM。** 小文件正确运行时，不再记录红色的“输出精度可能较低”警告；自动配置现在只有在你传入 `llm_auto=True` 时才会启用（付费）LLM 评分器——以前只要设置了 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY`，就会启用。如果你依赖这一行为，请传入 `llm_auto=True`，或在配置中设置 `llm_scorer`。 > > **v3.20.0：整数 ID 列不再导致零配置崩溃。** 如果 CSV 中的电话或账户列只包含数字（读取为 int64），在自动配置的阻塞处理中，`gm.dedupe(path)` 和 `goldenmatch dedupe` 会因 `ArrowNotImplementedError` 而失败；现在可以正常运行，而且此类列上的反向证据会参与评分，不再被悄悄禁用。CLI 摘要现在会说明统计内容——`12 records -> 7 entities (4 duplicate groups)`——并且 `result.total_entities` 与之相符。

---

试用

pip install goldenmatch
goldenmatch dedupe customers.csv

假设有一个 customers.csv，同一个人被录入了多次：

id	name	email	phone	address	zip
1	Maria Gonzalez	[email protected]	555-201-3344	14 Oak Street	62704
2	Maria Gonzales	[email protected]	(555) 201-3344	14 Oak St	62704
3	María González	[email protected]	5552013344	14 Oak St.	62704
4	James O'Neil	[email protected]	555-883-1200	902 Pine Avenue	84065
5	Jim O'Neill	[email protected]	555.883.1200	902 Pine Ave	84065
8	Thomas Becker	[email protected]	555-667-0192	77 Elm Court	97024
12	Thomas Baker	[email protected]	555-120-4455	41 Walnut Way	97024

GoldenMatch 会将第 1–3 行归为同一个人，第 4–5 行归为另一个人。Thomas Becker 和 Thomas Baker 虽然邮编相同，但会被分开。每组会合并为一条黄金记录，其中各字段采用最佳值。运行后会生成 <timestamp>_deduplicated.csv，每人一行（四条黄金记录，以及三位没有重复记录的人），以及仅包含合并记录的 <timestamp>_golden.csv。

在 Python 中：

import goldenmatch as gm

result = gm.dedupe("customers.csv")
print(result)       # DedupeResult(records=12, clusters=4, match_rate=75.0%)

result.deduplicated # one row per person: 7 here
result.golden       # one merged record per duplicate group
result.unique       # the records that had no duplicate
result.clusters     # which input rows belong together
result.config       # the matching config it chose

如果数据已在内存中，gm.dedupe_df(table) 可接收 pyarrow Table 或 polars DataFrame。

自动配置的选择及修改方式

这里没有黑箱。对于上述文件，自动配置会对 email 和 phone 执行精确匹配，对 name 和 address 执行模糊匹配，并且只比较 zip 相同的记录。result.config 保存了这些配置：

• 复用配置处理新数据：gm.dedupe("next_month.csv", config=result.config)。
• 使用自己的规则：gm.dedupe("customers.csv", exact=["email"], fuzzy={"name": 0.85})，或使用 YAML 配置。请参阅配置。

不止是一个文件

你的客户数据分散在 CRM、计费系统和三个无人维护的电子表格中。有些记录是重复的。有些记录属于同一家公司，只是拼写方式各不相同。没人能回答我们实际有多少客户，而基于这些数据构建的每个仪表盘都继承了这份不确定性。

性能超越 Splink 的实体解析，采用 Arrow 原生、Rust 驱动的高速引擎，无需调优；并为持久化身份层提供数据，让来自各个来源的混乱记录变成稳定的黄金实体，同时保留整条记录的 Customer-360 溯源信息。

零配置匹配，在混乱的客户记录上正面击败经过专家调优的 Splink；引擎采用 Arrow 原生、由 Rust 主导的架构，从笔记本电脑上的 CSV 到 2.5 亿行数据去重仅需 11.2 分钟，均已验证。它生成的身份信息存储在以事务为核心的控制平面中，提供稳定的 entity_id、字段级溯源、合并／拆分功能和防篡改审计日志，只需一次调用即可获取完整的 Customer 360。它甚至自主实现了自己的基础组件：字节级结果一致、速度快于 rapidfuzz / jellyfish / FAISS 的 Rust 内核，而非依赖外部组件。

Python · TypeScript · SQL，精度达到小数点后 4 位 · 原生支持 Postgres + DuckDB · 边缘 WASM · 70 多个 MCP 工具 · 击败手动调优的 Splink · 2.5 亿行数据仅需 11.2 分钟

_{网页工作台中的配对详情：簇成员、字段级差异，以及每对记录各一行的自然语言说明。运行 pip install goldenmatch[web]，然后运行 goldenmatch serve-ui <project>。查看更多截图 →}

---

你将获得：黄金实体

大多数实体解析工具会在生成集群后就此打住。GoldenMatch 则会更进一步：它会将杂乱的记录解析为持久的黄金实体，每个真实客户对应一个。即使反复运行也能保持稳定，每个字段都带有来源信息，并能通过一次调用回答“这是谁？每个值来自哪里？”。

• 稳定的身份，而非一次性的集群 ID。 每个实体都会获得一个稳定的 entity_id（UUIDv7），并在新数据到达后的多次运行中保持不变。记录会被吸收，实体会合并或拆分，但实体获得的 ID 就是下游系统可以依赖的 ID。每次运行的集群编号都会重新排列，而这些 ID 不会。
• 完整的记录溯源。 黄金记录的每个字段都能追溯到为其提供值的源记录：来源、最后一次出现的时间，以及选中该值的生存策略。未被选中的值也会保留，而不会被悄然丢弃。溯源信息覆盖整条统一记录，而不仅仅是匹配决策。
• 从设计上实现治理。 冲突值会根据明确的生存策略（最完整 · 来源优先级 · 最新值 · 多数投票）归并为一个最佳值；每次身份变更都会写入仅追加的事件时间线；日志则通过哈希链、防篡改审计加以封存，供审核人员（或另一种语言的实现）独立验证。

customer_360(entity_id) 会将以下内容整合为一次读取：黄金记录、各字段的溯源信息、所有关联的源记录、事件时间线，以及实体的关系邻域：

// customer_360("018f...c2a1")  (trimmed)
{
  "entity_id": "018f2b7e-...-c2a1", "confidence": 0.97, "record_count": 3,
  "sources": ["salesforce", "billing", "support"],
  "golden_record": { "name": "Ada Lovelace", "email": "[email protected]", "phone": "+1-555-0100" },
  "field_provenance": [
    { "field": "email", "value": "[email protected]",
      "winning_source": "billing", "winning_record_id": "billing:8821",
      "conflicting_values": [ { "value": "[email protected]", "source": "salesforce" } ] },
    { "field": "phone", "value": "+1-555-0100", "winning_source": "salesforce" }
  ],
  "timeline": [ { "kind": "created", "actor": "pipeline", "recorded_at": "2026-07-30T..." },
                { "kind": "absorbed_record", "reason": "matched billing:8821" } ],
  "relationships": [ { "other_entity_id": "018f...9d0e", "kind": "shares_address" } ]
}

当前已交付与正在推出的功能。 身份主干已达到生产级别并已合入 main：稳定的 entity_id、各字段的溯源信息、生存策略、合并/拆分、仅追加日志与审计链、跨渠道拼接，以及基于持久化索引的增量解析（新增记录无需完整重新运行即可解析）。上文的 customer_360() 服务视图和让它通过实时系统保持最新的来源注册表层，则是较新的、正在积极落地的部分。来源连接器（Snowflake、BigQuery、Salesforce、HubSpot）目前已交付；将它们接入主干的注册表仍在逐步推出。请参阅Customer 360 设计与 ADR。我们会明确标出这一区别，而不是将其模糊处理。

黄金实体位于控制平面；构建它的匹配逻辑则在计算引擎中运行。下一节将介绍这一区分。

---

一个产品，两套引擎

上方的黄金实体由两套引擎生成，它们真正优化的目标各不相同。将两者区分开是架构设计，而非实现细节（ADR 0047）。

flowchart LR
    src([source records])
    e360([golden entities · Customer 360])
    subgraph compute ["Identity Compute Engine: Arrow-native, Rust-authoritative"]
        match[block · score · cluster]
    end
    subgraph control ["Identity Control Plane: transaction-native state machine"]
        spine[stable ids · survivorship · merge/split · provenance · audit]
    end
    src --> compute -->|resolution batch + evidence| control --> e360
    control -.->|persisted index| compute

	Identity Compute Engine	Identity Control Plane
形态	在批量边界使用 Arrow，内核以 Rust 为权威实现	事务原生状态机（默认使用 SQLite · Postgres）
职责	分块、评分、聚类：高吞吐、向量化、每次运行结果确定	稳定 ID、生存策略、合并/拆分、溯源、仅追加审计
状态	每次调用均无状态；由测量驱动的内核化	持久、事务化、可重放、可审计
后端	DataFusion · Ray · Sail · Spark 都是可替换的执行后端，均不等同于 GoldenMatch	存储后端遵循同一套外部可观察语义

多种接入方式，同一个答案。 同一套能力可通过 Python、适用于边缘环境的 TypeScript（可选择使用运行相同 Rust 内核的 WASM 后端）、PostgreSQL 和 DuckDB 内的 SQL，以及 MCP / REST / A2A 提供，全部由规范 + 一致性验证治理，而非复制粘贴。每项能力都有一个权威实现；纯 Python / 独立 TS 路径则归类为经过一致性测试的回退方案。如果边界无法做到逐字节一致，我们会进行测量并标注，而不声称一致。

平台工程师为何应当关注：

• 计算层不会造成框架锁定。 它原生支持 Arrow，且后端可替换，因此你可以将繁重的匹配任务交给能够规划、溢写和分布式执行的查询引擎（已验证可处理 250M 行），而身份状态不会随之迁移。
• 身份层是真正的状态机，不是每次都重新构建的列式批处理。持久 ID、事务化合并/拆分、溯源和审计都是一等操作，可供你集成。
• 共享部分的行为保持一致。 SQL、Python 和 TypeScript 遵循同一份一致性规范，得出相同答案，因此你所依赖的接口不会悄然另创一套语义。

---

超越专家级的解析效果

身份层的质量取决于底层的匹配能力，而匹配从零配置开始。dedupe_df(df) 无需规则和训练数据即可运行：它会分析数据、选出合理的配置，并立即返回黄金记录。它所选的配置会通过 result.config 返回：可检查、可对比差异、可版本化。绝非黑箱。

• 开箱即超越专家。 在杂乱的客户记录上，可选的 Fellegi-Sunter 引擎在正面比较中胜过经过人工调优的 Splink：historical_50k 的成对 F1 为 0.827 vs 0.757，聚类 B³ 为 0.862 vs 0.788；使用同一评估器，可复现的对比测试。提供模糊、精确、概率（Fellegi-Sunter）和 LLM 评分器，以及通过 EM 训练的权重和校准后的分数。
• 持续修正，而非一次性运行。 零配置即可完成大部分工作；之后，每次运行都会检查一个免费的无监督信号，并在仍有优化空间时，将已排序且经过自验证的配置调整建议附加到 result.suggestions。只有在不会降低健康度代理指标时才会保留调整建议，因此建议不会让结果变差。dedupe_df(df, heal=True) 可在一次调用中应用调整并重新运行。无需成为专家，也能缩小与专家调优结果之间的差距。
• 保护隐私的记录链接。 无需共享原始数据即可跨组织匹配：使用 Bloom filter PPRL，在 FEBRL4 上的 F1 为 92.4%，并采用 HMAC 加盐编码。
• 自验证。 每个步骤都会运行预检和后检，并返回可检查的报告，而不是静默失败。这就是“先进，但绝非黑箱”的约定，让自动化身份层能够安全地作为构建基础。

也可处理非结构化输入：从 PDF 和图像中提取记录，再像处理其他来源一样解析它们（pip install goldenmatch[documents]）。

---

在你的技术栈中运行

引擎和身份层可通过你现有的使用界面接入技术栈，并提供相同的能力，这些能力由一致性测试统一保障（一个产品，两种引擎），而不是针对每种界面分别简单重写。

• 原生支持 SQL，功能一致。 同一组函数可在 PostgreSQL（pgrx 扩展）和 DuckDB 中运行：去重 · 匹配 · 评分 · 自动配置 + 遥测 · 身份图读取 · 分析 · evaluate · Fellegi-Sunter 评分 · GoldenFlow 转换。在数据仓库中完成解析，无需移出数据。
• 支持 Python 和边缘环境的 TypeScript。 全套工具也已发布到 npm，与 PyPI 并行。TS 核心不依赖任何依赖项，也不使用 node:*（适用于浏览器、Cloudflare Workers、Vercel Edge、Deno）；可选的 WebAssembly 后端（await enableWasm()）会切换到与 Python wheels 和 SQL UDF 使用的相同、无需 pyo3 的 Rust 内核，默认使用逐字节结果一致的纯 TS 实现。
• 默认原生支持 AI。 每个包都包含 MCP 服务、REST API 和 A2A Agent 界面（全套工具共提供 70+ 个 MCP 工具），并在 web、TUI、CLI、Postgres、DuckDB 和 MCP 中统一提供相同的 JSON 遥测格式。
• 支持 Spark，执行器无需 Python。 Rust 内核可通过一个 jar（spark.addArtifact("goldenmatch-spark.jar")）接入 Spark 集群，并通过 JNI 调用，因此执行器无需安装 goldenmatch 虚拟环境、打包环境或任何其他内容。Fellegi-Sunter 训练会以分布式方式运行在这条路径上——E 步会对一致模式执行 Spark GROUP BY，由集群负责计数，驱动程序只负责拟合模型。此路径侧重部署，而非吞吐量：测得 JVM 评分路径比 Python-worker 路径慢约 2.4 倍；使用它的理由是无需安装任何东西。
• 原生支持流水线。 提供 dbt 包（去重/匹配物化、质量测试、身份图读取）、GitHub Action（在数据质量回归时让 PR 失败）以及 13 个可直接使用的 Airflow DAG（部署）。
• 生产环境支持。 Postgres 同步、守护进程模式、血缘跟踪、审核队列。

跨语言一致性

表面一致性 并不意味着 可以将任一流水线阶段逐字节地从一种语言交给另一种语言。以下每项判定均由一致性测试工具实测得出，而非假定：

边界	判定
Identity graph DB	✅ 字节安全 + 可进行跨语言加密验证（由一个工具包写入的密封可通过另一个工具包验证）
score → cluster 和端到端拆分运行	✅ 字节安全，可复现单语言运行结果
Cluster JSON · config YAML · Learning Memory · record_fingerprint	✅ 可移植
字符串评分	🟡 容差为 4 位小数；阈值边界上的一对记录可能得出不同结果（只有使用共享的 WASM 评分器才能保证字节一致）
Standardize / 日期 · embeddings · auto-config controller	🟠 结果不同，不具备字节级可移植性
Distributed / Ray · document (VLM) ingest	⛔ 受架构限制，仅支持 Python

**经验法则：**在 cluster 或 identity 边界交接即可无缝衔接；不要在 standardize/日期、embeddings 或 controller 阶段拆分，否则无法保证位精确复现。完整详情及用于验证这些判定的可运行测试工具：跨语言一致性与阶段交接限制。

---

套件：通往主干的流水线

GoldenMatch 是核心，但解析效果取决于上游输入的质量。五个配套工具会在记录进入 identity 层之前对其进行清理、标准化和映射。每个工具都可以独立使用，也可以组合成一条流水线，并由 GoldenPipe 通过声明式配置进行编排：

flowchart LR
    raw([raw rows])
    golden([golden entities])
    subgraph orchestration ["GoldenPipe orchestrates"]
        direction LR
        infermap[InferMap] --> goldencheck[GoldenCheck] --> goldenflow[GoldenFlow] --> goldenmatch[GoldenMatch]
    end
    raw --> infermap
    goldenmatch --> golden

软件包	语言	在流水线中的作用	安装
InferMap	Python · TS	Schema 映射：在异构来源之间自动对齐列	pip install infermap · npm i infermap
GoldenCheck	Python · TS	数据质量扫描：编码、格式验证、异常检测	pip install goldencheck · npm i goldencheck
GoldenFlow	Python · TS	转换与标准化工具：电话、日期、地址、类别	pip install goldenflow · npm i goldenflow
GoldenMatch	Python · TS	零配置实体解析 → identity 主干。核心软件包。	pip install goldenmatch · npm i goldenmatch
GoldenAnalysis	Python · TS	分析与报告：将任一阶段的产物转为统一的 AnalysisReport + 跨运行回归检测	pip install goldenanalysis · npm i goldenanalysis
GoldenPipe	Python · TS	编排器：通过声明式 YAML 连接各步骤	pip install goldenpipe · npm i goldenpipe
golden-suite	Python	一行命令安装元软件包：完整套件 + 原生加速	pip install golden-suite

最详尽的文档位于 packages/python/goldenmatch/README.md（约 1,300 行：完整功能列表、CLI、架构、基准测试）。

共享组件

这些不是流水线阶段，而是各阶段共同依赖的组件，以及 Agent 可指向的统一入口。

软件包	说明	安装
goldencheck-types	共享的规范字段类型注册表：为所有软件包和两种语言中的字段类型 含义 提供唯一事实来源	pip install goldencheck-types · npm i goldencheck-types
goldensuite-mcp	一个 MCP 服务，通过单一端点（stdio 或 Streamable HTTP）提供套件中的所有工具	pip install goldensuite-mcp

自有库（独立发布）

该套件自有字符串匹配基础组件，而非依赖外部库：提供字节级一致的即插即用替代品，并单独发布，因此也可在套件之外使用。

库	替代	功能	安装
goldenfuzz	rapidfuzz	模糊字符串评分器 + 完整的 fuzz.* 组合函数系列 + 一对多 extract/cdist。字节级一致（经 oracle 模糊测试），短字符串处理更快。	pip install goldenfuzz · cargo add goldenfuzz-core
goldenphonetic	jellyfish	语音编码器：soundex / metaphone / nysiis / match-rating。字节级一致（包含 6,000 个输入 + 2,500 个配对的模糊测试语料库），纯 Rust 实现，零依赖。	pip install goldenphonetic · cargo add goldenphonetic-core
goldenmatch-hnsw	FAISS IndexHNSWFlat	纯 Rust 实现的 HNSW 近似最近邻索引（零 C 依赖）。为 Python、Rust 和 TS/WASM 中基于嵌入的阻塞提供支持。	pip install goldenmatch-hnsw

知识图谱

实体解析是大多数 GraphRAG 工作流表现最差的环节：同一实体的重复表面形式散落在不同文档中。有两个包将 GoldenMatch 的解析能力用于此场景：

包	功能	状态
goldenmatch-kg	将 GoldenMatch 解析作为实体解析（ER）阶段，直接接入现有 KG 框架（neo4j-graphrag、LlamaIndex、Graphiti）。	仓库内 · 未发布（有意为之）
goldengraph	从文本构建自己的 KG：text → LLM extraction → GoldenMatch resolution → durable bi-temporal store。Rust 引擎；ER 是其差异化优势。	仓库内 · 首次 PyPI 发布待定

以测量结果为准，而非口头断言（ER-KG-Bench）：在带标签的数据集上，解析得分为 F1 0.602，高于 Neo4j-KGBuilder（0.456）、neo4j-graphrag（0.403）以及 MS-GraphRAG / LightRAG / Cognee / mem0（0.066）。解析后的图还能实现基于段落窗口的 RAG 在结构上无法做到的两件事：精确聚合（不受规模影响；而 RAG 的召回率在不同集群大小区间内从 0.99 → 0.64 急剧下降）和按时间点查询（过去日期查询得分为 1.000，对比 0.002）。

---

规模与基准测试

每个重点数据都对应一个已提交的运行脚本（scripts/run_benchmarks.py）；每项数据对应的命令、数据集 URL 和带容差的预期输出，请参阅 docs/reproducing-benchmarks.md。

• 在贴近客户实际的数据上准确。 NC Voter 的 F1 为 0.9719（真实数据样本），Febrl3 的 F1 为 0.9912；在 Splink 评测的每个数据集上，可选的 Fellegi-Sunter 路径都正面胜过经过手动调优的 Splink（对比测试）。（对于记录链接领域，书目数据集 DBLP-ACM 的 F1 为 96.4%，但重点在于客户身份识别。）
• 保护隐私。 PPRL 在 FEBRL4 上的 F1 为 92.4%，可在各方之间进行匹配，无需共享原始数据。
• 规模范围（docs/scale-envelope.md）：各后端适用范围（内存/分桶至数百万条 · DuckDB 外存处理至约 5,000 万条 · Ray 分布式处理不少于 5,000 万条）、阻塞大小的失效模式，以及用于选择后端的决策树。 已在 Ray 层级验证：在 5 节点 Ray 集群上，对完整的 1 亿行数据进行去重，用时 9.2 分钟（554 秒），准确恢复了 20,000,000 条黄金记录，驱动程序峰值内存为 0.36 GB RSS。（更大的 2.5 亿行 / 11.2 分钟这一亮眼成绩属于 Spark 层级，使用的是不同的集群配置——两者是不同的运行路径，不是后者取代前者；而且下面这个数据才具备完整召回保证。）默认的分布式路径可完整召回：无论如何对输入数据分区，重复记录都能正确合并（基于阻塞键 shuffle 的评分 + 分布式随机收缩 WCC），并且整个流程始终无需将数据收集到驱动程序。配置：configs/distributed-100m.yaml。

**Fellegi-Sunter 在 Spark 上进行分布式训练：**E 步归结为一次针对一致性模式的 Spark GROUP BY，因此训练成本取决于不同比较向量的数量（上限为 prod(levels + 1)），而非配对数量。在一台真实的 2 个工作节点 Spark 集群上测得（执行器仅有 jar，未安装 Python），行数从 100 万增至 500 万：候选配对数增长 5.00 倍，分布式计数阶段耗时增长 5.25 倍，而不同模式仅增长 3.0%（433 → 446），驱动程序端的 EM 仍只耗时 0.01 秒。这正是该层级赖以运行的特性——集群负责处理数据，驱动程序的工作量保持不变。

**在真实 Spark 集群上与 Splink 正面对比，数据规模为 5000 万行。**两个引擎运行于同一台 5 节点集群，使用同一份测试数据、同一套共享指标实现；Splink 则按照其自身性能指南的建议进行配置——通过 break_lineage_method="parquet" 写入真实分布式文件系统，将 shuffle 分区数设为集群核心数的 5 倍，并使用相同的 48 GB 执行器。共处理 463,923,179 个候选配对，两者的评分结果一致：

	GoldenMatch	Splink	比率
总耗时	552 秒	1,054 秒	1.91 倍
u / estimate	3.5 秒	30.8 秒	8.78 倍
shuffle 写入量	86.8 GB	212.1 GB	2.44 倍
阶段数	119	394	3.31 倍
执行器 CPU	31,300 秒	51,572 秒	1.65 倍

同时报告这些数据，是因为只公布胜出结果的基准测试不足以作为证据：随着规模增大，优势仍在缩小（100 万行时为 2.54 倍 → 5000 万行时为 1.91 倍）；该运行路径的单次运行结果波动约 16%，因此任何单个比率都不应被过分看重；零溢出的规模受限于绘制该曲线时使用的版本（5000 万行时属实，1 亿行时溢出 56.4 GB，2.5 亿行时溢出 201.3 GB——之后通过 #2698 将 2.5 亿行时的溢出降为零，因此这一说明描述的是曲线，而不是已发布的运行路径）；测试数据是合成的；其中的准确率数据不能作为准确率结论——相关内容请参阅 横向评测。**后续测得：**在同一台 5 节点集群上，2.5 亿行 / 23.2 亿个配对耗时 670 秒，没有执行器退出，失败任务数为零，每百万个配对耗时 0.289 秒——比该曲线首次测得的 2,766 秒快 4.13 倍，执行器 CPU 用量减少 3.1 倍，零溢出，训练出的模型逐字节相同。成本仍与配对数而非行数呈线性关系；单位常数降至原来的四分之一。此前有四次对比尝试无效，因为我们错误配置了 Splink；每个问题及其影响均已与结果一并记录。完整方法、注意事项和复现命令。

以下三个可复现的真实世界工作流使用公共数据进行大规模处理：

• shell-company-network：跨 ICIJ Offshore Leaks、OpenSanctions、GLEIF 和 UK PSC 进行调查实体解析。与单一数据源基线相比，分析师用于分类的工时减少 62.5%。
• vuln-attribution：在一台 64GB 运行器上约 5 分钟内，处理 40 个来源的 6,126,895 条开源软件漏洞记录 → 847,475 个规范化漏洞。
• sanctions-reconciliation：覆盖 50 多个司法管辖区的 85 份公开制裁名单。

---

安装与快速开始

30 秒内对 CSV 去重，无需配置，写入 <timestamp>_golden.csv：

pip install goldenmatch && goldenmatch dedupe customers.csv

import goldenmatch as gm

result = gm.dedupe("customers.csv")               # zero-config
print(result)                                     # DedupeResult(records=12, clusters=4, match_rate=75.0%)
result.to_csv("golden.csv")                       # one merged record per duplicate group

result = gm.dedupe("customers.csv",               # or be explicit
    exact=["email"], fuzzy={"name": 0.85, "zip": 0.95}, blocking=["zip"], threshold=0.85)

import { dedupe } from "goldenmatch";           // edge-safe: browsers, Vercel Edge, Workers, Deno
const result = dedupe(rows, { fuzzy: { name: 0.85 }, blocking: ["zip"], threshold: 0.85 });

整个套件，已配置为追求速度。 golden-suite 会引入所有包及原生（Rust）内核，并固定版本且默认使用性能优化配置。原生 wheel 是硬性依赖：没有对应 wheel 的平台会明确报错，而不会悄悄改用较慢的纯 Python 路径。

pip install golden-suite
golden-suite doctor        # verify every package + native kernel is importable and healthy
golden-suite optimize      # repair / re-enable the perf-optimized config

pip install golden-suite[mcp]     # + aggregator MCP server (every tool, one endpoint)
pip install golden-suite[all]     # everything

仅安装 GoldenMatch。 提供丰富的可选附加项，只为实际使用的功能付费（常见平台默认启用原生加速）：

pip install goldenmatch                    # core (CSV in, CSV out) + native
pip install goldenmatch[documents]         # + PDF/image ingest (resolve unstructured input)
pip install goldenmatch[embeddings]        # + sentence-transformers, FAISS
pip install goldenmatch[llm]               # + Claude / OpenAI for LLM boost
pip install goldenmatch[ray]               # + Ray distributed backend (50M+ rows)
pip install goldenmatch[postgres]          # + Postgres sync  (also: [snowflake] [bigquery] [databricks] [salesforce])
pip install goldenmatch[mcp]               # + MCP server     (also: [agent] A2A, [web] browser workbench)

Web 工作台。 执行 pip install 'goldenmatch[web]'，然后运行 goldenmatch serve-ui my-project（打开 http://localhost:5050）：编辑规则并实时验证、在抽样数据上预览、标记数据对（同步到 Learning Memory）、比较运行结果。

更多内容： examples/，涵盖 Python（快速入门、完整管道、客户 360、PPRL、MCP 客户端） · TypeScript（快速入门、Vercel Edge、MCP 客户端） · Airflow。

---

部署

远程 MCP。 托管端点需要 bearer token——它提供可在服务端读取和写入文件的工具，因此并非开放访问。请向维护者申请 token，或自行托管：goldenmatch mcp-serve --transport http 使用的就是同一服务。

{ "mcpServers": { "goldenmatch": {
    "url": "https://goldenmatch-mcp-production.up.railway.app/mcp/",
    "headers": { "Authorization": "Bearer YOUR_TOKEN" }
} } }

在 loopback 上自行托管无需 token；如果未设置 GOLDENMATCH_MCP_TOKEN，则会拒绝绑定到公共接口，而不会开放服务。

容器。 每个包都会在 GHCR 上提供多架构镜像（linux/amd64 + arm64），可匿名拉取：

docker run -p 8300:8300 ghcr.io/benseverndev-oss/goldensuite-mcp:latest   # one container, every tool
docker run -p 8200:8200 ghcr.io/benseverndev-oss/goldenmatch-mcp:latest   # per-package (also goldencheck/goldenflow/goldenpipe/infermap)
docker run -e POSTGRES_PASSWORD=secret ghcr.io/benseverndev-oss/goldenmatch-extensions:latest   # Postgres + extension

Airflow。 examples/airflow/ 提供 13 个可直接使用的 DAG（TaskFlow API、Airflow 2.7+ / 3.x；幂等且受标记保护），按生命周期阶段分组：

分组	DAG
核心管道	daily_dedupe、incremental_match、warehouse_native（Snowflake）、customer_360、identity_graph
隐私	pprl_linkage（双方 PPRL）
接入与监控	schema_align_and_load、schema_drift_alarm、quality_gate
反馈循环	review_worker、active_learning
运营化	reverse_etl（Salesforce/HubSpot）、backfill

---

仓库布局

goldenmatch/
├── packages/
│   ├── python/        goldenmatch · goldencheck · goldenflow · goldenpipe · infermap · goldenanalysis
│   │                  goldensuite-mcp (aggregator) · golden-suite (meta) · goldengraph · goldenmatch-kg
│   ├── typescript/    full TS ports (edge-safe cores + WASM) · goldencheck-types
│   ├── rust/extensions/  Postgres pgrx + DuckDB UDFs + native kernels + owned libraries (own Cargo workspace)
│   ├── dbt/goldensuite/  dbt materializations, tests, macros
│   └── actions/goldencheck/  GitHub Action
├── examples/          python · typescript · airflow (drop-in DAGs)
├── context-network/   architecture decisions + design docs (ADRs, the two-engine frame, Customer 360)
├── docs/superpowers/  design specs and implementation plans
└── justfile · pyproject.toml (uv workspace) · pnpm-workspace.yaml (Turborepo) · .github/workflows/ci.yml

• Cargo：没有根工作区。 packages/rust/extensions/ 本身就是一个 Cargo 工作区（postgres crate 因 pgrx 而被排除）；Cargo 命令需在该目录内运行。
• TypeScript：一个 pnpm 工作区。 packages/typescript/* 构成一个 pnpm + Turborepo 工作区。

just install   # uv sync + per-package npm install + cargo fetch
just test      # all languages   ·   just lint   ·   just build

贡献

• 在 feature/<name> 分支上开发功能；通过 squash PR 合并。标题使用：feat: / fix: / docs:。
• 如果更改涉及三种语言，必须通过所有语言的测试；packages/typescript/goldenmatch/tests/parity/ 中的 parity 测试框架会强制校验 Python ↔ TypeScript 评分器精度一致到 4 位小数。
• 架构更改须在同一个 PR 中遵循（或修订）one-product-two-engines frame。设计依据记录在 context-network/decisions/ 和 docs/superpowers/specs/ 中。

corepack enable                               # one-time, picks up [email protected]
pnpm install
pnpm turbo run build test typecheck           # full pipeline (cached after first run)

**Windows：**启用 Developer Mode，以便 pnpm install 创建符号链接；如果 corepack enable 需要管理员权限，可使用等效命令 npm i -g [email protected]。

---

_{本代码仓库于 2026-05-01 由 8 个同级代码仓库合并而成，并通过 git filter-repo 并入 goldenmatch（完整保留历史记录）。由 Ben Severn 构建。采用 MIT 许可证，详见 LICENSE。}