内容
# 精确类型
[](https://github.com/meridian-online/finetype/actions/workflows/ci.yml)
> **早期发布** — FineType 正在积极开发中。预计在不同版本之间，分类标签、命令行参数、库 API 和模型格式可能会发生重大变化。如果稳定性对您的使用场景很重要，请固定到特定版本。
文本数据的精确格式检测。FineType 将字符串分类为丰富的 245 个语义类型 — 每个类型都是一个**转换契约**，保证 DuckDB 投射表达式将成功。
```
# 指向整个列 — 准确的路径。列类型比单独的值更准确：FineType 采样列并运行其
# 守卫 → 否决 → 恢复栈在分布上，因此它比单个隔离值有更多的上下文。
$ printf '541511\n541512\n236220\n' | finetype infer
表示.数值.整数
# 单个值也可以 — 价值决定类型的结论：
$ finetype infer -i "192.168.1.1"
技术.互联网.IPv4
$ finetype infer -i "2024-01-15T10:30:00Z"
日期时间.时间戳.ISO_8601
$ finetype infer -i "hello@example.com"
身份.人员.电子邮件
```
## 功能
- **245 个语义类型**，涵盖 7 个领域 — 日期、时间、IP地址、电子邮件、UUID、金融标识符、货币、地理空间格式、医疗代码等
- **转换契约** — 每个类型都映射到一个 DuckDB SQL 表达式，保证成功的解析。99.9% 的行动能力，涵盖 120 个测试类型。
- **区域感知** — 验证 65+ 个地区的邮政编码，46+ 个地区的电话号码，32+ 个地区的月份/天名称
- **MCP 服务器** — `finetype mcp` 通过 [模型上下文协议](https://modelcontextprotocol.io/) 向 AI 代理公开类型推理
- **DuckDB 扩展** — `finetype()`、`finetype_detail()`、`finetype_cast()`、`finetype_unpack()`、`finetype_validate()` 标量函数
- **基于模式的验证** — `finetype validate data.csv schema.json --db out.db --table orders` 在单个通道中物化类型化的 DuckDB 表（应用每列转换）以及 `finetype_reject_errors` 边车
- **纯 Rust** — 无 Python 运行时或依赖
## 安装
> **运行时依赖：** [`duckdb`](https://duckdb.org/docs/installation) CLI 必须在 `PATH` 上。`finetype profile` 和 `finetype validate` 调用它来处理所有 CSV/Parquet 摄取（`brew install duckdb` 或您的平台包管理器）。这是一个 shell 调用，而不是链接 — 发布二进制文件在不同平台上保持不变。
### Homebrew（macOS / Linux）
```bash
brew install meridian-online/tap/finetype
```
### Cargo
```bash
cargo install finetype-cli
```
### 从源代码构建
```bash
git clone https://github.com/meridian-online/finetype
cd finetype
cargo build --release
./target/release/finetype --version
```
## 用法
### 命令行界面
```bash
# 分类一列值 — 准确的路径（基于分布）。
# 按行管道一个值，或使用 -f 传递文件。FineType 采样列
# 并从整个分布中类型，因此 guard/veto 栈比单个值有更多的上下文。
# 默认模式为列；添加 --confidence 查看样本数量。
printf '541511\n541512\n236220\n' | finetype infer --confidence
# 表示.数值.整数
# 置信度：0.7933（3 个样本）
finetype infer -f column_values.txt --mode column
# 分类单个值（价值决定类型的结论）
finetype infer -i "bc89:60a9:23b8:c1e9:3924:56de:3eb1:3b90"
# 配置 CSV 文件 — 检测所有列类型
finetype profile -f data.csv
# 启动 MCP 服务器以集成 AI 代理
finetype mcp
# 显示分类法（按领域、类别筛选）
finetype taxonomy --domain datetime
# 为类型导出 JSON 模式（支持通配符模式）
finetype taxonomy "datetime.date.*" -o json-schema
# 验证 CSV 文件是否符合 JSON 模式 — 写入 DuckDB .db 文件
# 用户的有类型表（有效行、应用每列转换）+ `finetype_reject_errors` 边车
# （引擎拒绝 error_type='SEMANTIC_TYPE'；单元格通过验证但
# 转换失败，error_type='TRANSFORM_FAILED'）。
# 退出代码：0 无拒绝 / 1 拒绝 / 2 错误。需要在 PATH 上安装 `duckdb`。
finetype profile -f data.csv -o json-schema > schema.json
finetype validate data.csv schema.json --db out.db --table orders
duckdb out.db -c "SELECT column_name, error_type, constraint_failed, expected_type, type_confidence FROM finetype_reject_errors;"
```
### DuckDB 扩展
> **安装：** 签名的社区构建（`INSTALL finetype FROM community;`）正在重新发布，目前在最近的 DuckDB 版本中不可用。在它发布之前，请从此仓库使用 `make build-release` 构建扩展并加载它 — 参见 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#duckdb-extension-build)。
```sql
-- 加载本地构建的扩展（使用 -unsigned 启动 DuckDB）
LOAD './target/release/finetype_duckdb.duckdb_extension';
-- 分类单个值
SELECT finetype('192.168.1.1');
-- → '技术.互联网.IPv4'
-- 分类列，详细输出（类型、置信度、DuckDB 广泛类型）
SELECT finetype_detail(value) FROM my_table;
-- → '{"type":"datetime.date.mdy_slash","confidence":0.98,"broad_type":"DATE"}'
-- 规范化值以实现安全的 TRY_CAST（日期 → ISO，布尔值 → true/false）
SELECT finetype_cast(value) FROM my_table;
-- 递归分类 JSON 字段
SELECT finetype_unpack(json_col) FROM my_table;
```
首次使用时，扩展程序会从 HuggingFace 下载模型权重并在本地缓存。设置 `FINETYPE_MODEL_DIR` 以使用本地模型路径代替。
### MCP 服务器
FineType 通过 [模型上下文协议](https://modelcontextprotocol.io/) 向 AI 代理公开类型推理。配置您的 MCP 客户端以启动 `finetype mcp` 作为 stdio 子进程。
MCP 工具表面反映了 CLI（一个功能表面，由对等测试强制执行）：
| 工具 | 目的 |
|---|---|
| `infer` | 分类值（单值或列模式，带表头） |
| `profile` | 配置 CSV/Parquet/JSON 文件（路径或内联数据）中的所有列；`format: "json-schema"` 用于表级模式 |
| `taxonomy` | 搜索/筛选类型分类法；使用 `key`/glob + `format: "json-schema"`，导出每类型 JSON 模式 |
| `validate` | 基于模式的 CSV 验证 — 有效/无效计数 + 错误详细信息 |
| `generate` | 为类型生成合成样本数据 |
**资源：** `finetype://taxonomy`, `finetype://taxonomy/{domain}`, `finetype://taxonomy/{domain}.{category}.{type}`
### 作为库
发布的模型是列级多分支分类器与 Model2Vec 头编码器配对：
```rust
use finetype_model::{ColumnClassifier, ColumnConfig, Model2VecResources, MultiBranchClassifier};
let mb = MultiBranchClassifier::load("models/default")?;
let mut classifier = ColumnClassifier::with_multi_branch(mb, ColumnConfig::default());
classifier.set_model2vec(Model2VecResources::load("models/model2vec")?);
let result = classifier.classify_column(&["hello@example.com".to_string()])?;
println!("{} (confidence: {:.2})", result.label, result.confidence);
// → 身份.人员.电子邮件（置信度：0.97）
```
## 分类法
FineType 识别 **245 个类型**，跨越 **7 个领域**：
| 领域 | 类型 | 示例 |
|--------|-------|----------|
| `datetime` | 87 | ISO 8601、RFC 2822、Unix 时间戳、CJK 日期、Apache CLF、时区、月份/天名称（32+ 地区） |
| `representation` | 32 | 整数、浮点数、布尔值、数字代码、十六进制颜色、JSON、CAS 号码、SMILES、InChI |
| `technology` | 29 | IPv4/v6、MAC、URL、UUID、ULID、DOI、哈希、JWT、AWS ARN、Docker 引用、CIDR、git SHA |
| `identity` | 33 | 名称、电子邮件、电话号码（46+ 地区）、信用卡、SSN、VIN、医疗代码（ICD-10、CPT、LOINC） |
| `finance` | 28 | IBAN、SWIFT/BIC、ISIN、CUSIP、SEDOL、LEI、FIGI、货币金额（7 种格式变体）、路由号码 |
| `geography` | 25 | 经纬度、国家、城市、邮政编码（65+ 地区）、WKT、GeoJSON、H3、地理哈希、Plus 代码、MGRS |
| `container` | 11 | JSON 对象、CSV 行、查询字符串、键值对 |
每个类型都是一个**转换契约** — 如果 FineType 预测 `datetime.date.mdy_slash`，则保证 `strptime(value, '%m/%d/%Y')::DATE` 将成功。
标签格式：`{domain}.{category}.{type}`（例如，`technology.internet.ip_v4`）。地区特定类型追加地区后缀：`identity.person.phone_number.EN_AU`。
参见 [`labels/`](labels/) 以获取完整的分类法定义。
## 性能
FineType 运行一个两阶段的管道：一个**语义**分类器（多分支模型）预测一个广泛的类型，然后一个**确定性**精炼层（基于值的规则和否决）将其锐化为叶类型并强制转换契约。
| 指标 | 值 |
|--------|-------|
| 准确率 | 0.81 在 931 列人类验证的金色语料库上 |
| 行动能力 | 99.9%（232,321/232,541 个值在 120 个类型上转换） |
| 模型类别 | 244 |
| 配置文件（模型加载 + 分类） | ~150 毫秒；~180 MB 峰值 RSS |
双编码器模型（potion-8M 值分支 + potion-4M 头分支）是主要的占用；价值可确定的输入（电子邮件、IP地址、ISO 日期时间）采用确定性快速路径，完全跳过模型加载（~50 毫秒）。
## 已知限制
### DuckDB `strptime` 地区限制
DuckDB 的 `strptime` 函数仅接受英文月份和日期名称。非英文日期，如 `6 janvier 2025`，将失败，错误信息为 `strptime(col, '%d %B %Y')`。
**受影响的类型：** `datetime.date.long_full_month`、`datetime.date.abbreviated_month` 和具有非英文月份/日期名称的相关时间戳变体。
**解决方法：** FineType 的地区检测正确识别非英文日期，但转换必须首先标准化为英文。有关详细信息，请参见 [地区支持指南](docs/LOCALE_GUIDE.md)。
## 开发
参见 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) 以获取训练管道、DuckDB 扩展构建和贡献者设置。有关架构详细信息，请参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
```bash
cargo build --release # 构建
cargo test --all # 运行测试
cargo run --release -- check # 验证分类法对齐
make eval-report # 运行评估套件
```
## 许可证
MIT — 参见 [`LICENSE`](LICENSE)
## 贡献
欢迎贡献！请开启一个问题或 PR。
## 鸣谢
[Meridian](https://meridian.online) 项目的一部分。
使用 [Candle](https://github.com/huggingface/candle)（Rust ML）、[DuckDB](https://duckdb.org)、[QSV](https://github.com/dathere/qsv)（CSV 工具包）、[rmcp](https://github.com/modelcontextprotocol/rust-sdk)（MCP SDK）和 [Serde](https://serde.rs) 构建。
训练 TUI 仪表盘灵感来自 [Burn](https://github.com/tracel-ai/burn) 的训练渲染器（[`burn-train`](https://github.com/tracel-ai/burn/tree/main/crates/burn-train/src/renderer/tui)）。
