# GenderAPI.io V2 的数据来源与盘点

> 了解 V2 响应的来源、注明日期的数据库盘点、样本一致性检查，以及已发布来源文档的局限。

Canonical HTML: https://www.genderapi.io/zh/data-provenance

Last reviewed: 2026-09-29

## V2 中的 source 是什么意思？

source 字段表示最终结果由哪条路径产生：存储数据集的查询、AI 预测，或者没有选中任何来源。它并不指向某条记录的原始发布者，不是许可证明，也不能保证预测正确。

本指南介绍当前的 V2 响应约定，以及由 GenderAPI.io 自行编制的数据库概况。下面的观察属于盘点和一致性检查；经过验证的原始来源目录和独立的准确率评估尚未发布。

| source | 含义 | 不能说明的内容 |
| --- | --- | --- |
| `dataset` | 选中了一条存储记录；频次完全相同时，性别仍可能未知 | 原始发布者、收集方法、许可、记录的时效，或观测之间的独立性 |
| `ai` | 最终答案来自已配置的 AI 预测路径；gender 仍可能为 null | 计数样本、数据集引用或经过校准的预测准确率 |
| `none` | 仅使用数据集时，最终结果没有选中任何存储记录 | 输入在任何人群或语言中都不存在可能的姓名关联 |

## 数据库概况：2026年9月26日

集合元数据读取于 2026-09-26T15:28:18.227Z，随机样本抽取于 2026-09-26T15:31:54.045Z。两项文档数量分别来自对应集合的 MongoDB collStats 元数据，而不是单独进行的完整计数。通用集合包含姓名记录，国家/地区专属集合包含姓名与国家/地区的组合。请不要把这两个数字相加，得出唯一姓名或唯一人员的总数。

对于每个集合，MongoDB 随机选取了 5,000 个文档，并在数据库服务器上计算了下面的汇总检查。公开报告不包含姓名或原始数据。这些是 GenderAPI.io 在生产数据库上所做的观察，不是独立审计，也不是冻结的评估数据集。这些检查关注的是计数的一致性，而不是预测的准确率、唯一人员或姓名的数量，也不是 API 的覆盖范围。

| 观察项 | 通用记录 | 国家/地区专属记录 |
| --- | --- | --- |
| 集合 | general | country-specific |
| 元数据中的文档数量 | 2,483,220 | 4,080,692 |
| 存储的唯一键 | name | name + country |
| 随机选取的文档 | 5,000 | 5,000 |
| 样本中未通过的数值检查 | 0 | 0 |
| 样本中 male + female 不等于 total | 0 | 0 |
| 样本中 male 与 female 频次相同 | 124 | 94 |
| 样本中存在 updated_at 字段 | 667 / 5,000 | 741 / 5,000 |

- [下载注明日期的汇总概况（JSON）](https://www.genderapi.io/data-evidence/v2-dataset-profile.json)

## 数据库检查说明了什么

数值检查要求 total 为正的安全整数，且 male 和 female 频次为有限值并介于零和 total 之间。另一项检查比较 male + female 与 total。样本中的所有计数都通过了检查；这并不意味着集合中的所有记录都一致，也不意味着某个预测是正确的。

在通用集合的样本中，有 124 条记录的 male 与 female 频次相同；在国家/地区专属集合的样本中有 94 条。这些是相同的存储频次，并不是经过独立验证的含义不明确的身份，也不是 API 的未知结果率。API 的实际结果取决于输入、Redis 的可用性、候选项的选择和 AI 选项。

于 2026-09-26T15:33:13.811Z 对通用集合中 country 字段进行的单独盘点，发现了 244 个不同的存储值：其中 239 个为两个大写字母的格式，5 个为其他格式。是否符合 ISO、记录按国家/地区的分布以及所支持国家/地区的覆盖范围均未测量。这些数字并不是所支持国家/地区的数量。

两个样本中都没有发现来源或许可字段。这并不能证明每条记录或外部系统中都缺少来源信息：某个字段存在与否，并不能证明来源的许可情况。部分记录中存在数值形式的 updated_at 字段，但其值和含义尚未验证；它并不能说明数据的时效或更新计划。

V2 通过 Redis 进行数据集查询。2026年9月26日，GenderAPI.io 作为系统管理方确认 MongoDB 和 Redis 包含相同的数据集。这种一致性基于该确认：尚未对两个数据库进行独立比较，这项核查仍待完成。上面的盘点描述的是存储记录；API 响应的覆盖范围还取决于提交的输入、候选项匹配和 AI 选项。样本的抽取未使用固定种子，读取时没有冻结快照，处理时也没有独立的参考标签；它们无法衡量预测准确率、校准或作答覆盖率。

- [如何测量准确率和覆盖率](https://www.genderapi.io/zh/accuracy-methodology)

## 在响应中追踪依据

| 字段 | 含义 | 局限 |
| --- | --- | --- |
| `input` | 重复提交的类型、值和国家/地区背景 | 输入值并不是经过独立验证的身份信息 |
| `match.name / match.method` | 显示所选的候选项，以及它是经过规范化、作为部分或子字符串提取的，还是由模型预测的 | 与某个部分匹配，并不能保证从完整姓名或用户名中提取到了真实的名字 |
| `match.scope / match.country` | 显示所选记录来自国家/地区专属查询还是全局查询 | 提供了国家/地区，并不能保证存在该国家/地区的专属记录 |
| `sample_count` | 所选记录中存储的总计数；AI 预测时为 null | 不一定代表唯一人员、独立收集的观测，或准确率评估的样本量 |
| `confidence / confidence_kind` | 区分根据存储频次计算出的比值与模型给出的值 | 两者都不是关于一个人性别认同的经过验证的概率 |
| `country / country_source` | 返回记录的国家/地区元数据，或 AI 给出的姓名与国家/地区之间的关联（如有） | 不能说明国籍、居住地或经过验证的出身，也不能证明提交的国家/地区得到了匹配 |

- [完整的 V2 响应文档](https://www.genderapi.io/zh/docs/v2/responses)

## 输入匹配如何影响结果

数据集查询会规范化文本并从中提取候选项。对于电子邮箱地址，候选项来自 @ 之前的部分；对于用户名，开头可选的 @ 会被去掉。电子邮箱地址和用户名的普通查询还可能检查有限的子字符串。如果有多条候选记录，会选择存储总计数最大的那一条。它可能是与想要的名字不同的部分。

如果提供了国家/地区背景，查询会针对每个候选项检查国家/地区专属记录，不存在时再检查全局记录。最终结果会给出所选的匹配。含义不明确的国家/地区专属记录不会被自动替换为该候选项的全局记录。

普通的 AI 提示词寻找可识别的名字。forceToGenderize 还允许通过个人昵称或别名建立关联：在此模式下，非 null 的性别加上 name: null 是有效的结果。这是不同的预测任务，应分别评估。

- [姓名查询](https://www.genderapi.io/zh/docs/v2/gender-from-name)
- [电子邮箱地址查询](https://www.genderapi.io/zh/docs/v2/gender-from-email)
- [用户名查询](https://www.genderapi.io/zh/docs/v2/gender-from-username)
- [AI 选项](https://www.genderapi.io/zh/docs/v2/ai-options)

## 数据集查询与 AI 处理

使用 AI 时，V2 会把提交的 type、value 和国家/地区背景发送给已配置的预测 AI 服务。对于电子邮箱地址，提示词会要求模型忽略域名和加号之后的后缀；这并不能保证在 AI 处理之前这些字符已从值中删除。如果您的工作流程需要仅基于数据集的预测，请使用 ai_mode: off，且不要使用 forceToGenderize。

AI 响应的验证会检查 JSON 字段、字段类型以及字段之间的一致性。它并不能证明返回的名字、性别关联或国家/地区关联是正确的。公开结果不包含模型的标识或版本，也不包含支持该预测的任何来源。

| 选项 | 预测路径 | 返回的依据 |
| --- | --- | --- |
| ai_mode: off | 仅查询数据集 | 所选记录的元数据，或没有选中记录的未知结果 |
| ai_mode: fallback | 先查询数据集；没有返回性别时使用 AI | 最终路径的依据，而不是数据集与 AI 合并后的样本 |
| ai_mode: always | 直接使用已配置的 AI 预测路径 | 模型给出的值，或 confidence 为 null 的未知结果；sample_count 始终为 null |
| forceToGenderize: true | 查询数据集，没有结果时使用考虑昵称的 AI | 数据集的依据，或模型给出的基于昵称的关联；name 可能为 null |

- [AI 选项与参数兼容性](https://www.genderapi.io/zh/docs/v2/ai-options)
- [隐私政策](https://www.genderapi.io/zh/privacy-policy)

## 尚未发布的来源文档

此处未发布经过验证的来源目录。仅凭响应约定和实现行为，无法验证数据的出处、来源的使用权、代表性或标签质量。在对具体来源作出说明之前，需要记录并验证以下信息。

本次文档审查并不判定原始来源是否受许可覆盖，也不判定其是否完整。它说明的是公开可用依据的局限。如果您的使用场景需要评估某个具体来源，请联系 GenderAPI.io。

| 依据 | 所需文档 | 公开状态 |
| --- | --- | --- |
| 出处与使用权 | 具名的来源或发布者、收集时间段、许可或其他有记录的使用依据 | 此处未发布经过验证的目录 |
| 处理历史 | 转换、规范化、去重、汇总，以及任何合成或模型生成的贡献 | 不会体现在 source: dataset 标签中 |
| 人群覆盖 | 国家/地区与文字的覆盖、选取程序、标签定义和有记录的偏差 | 此处未发布经过独立评估的覆盖数据 |
| 时效 | 快照标识、每个来源的更新日期以及相应的更新计划 | V2 响应不包含每条记录的时效信息或快照标识 |
| 质量与更正 | 验证结果、重叠检查、更正与删除的处理，以及审核责任 | 此处未发布按来源划分的审计结果 |

## 数据保护、处理与负责任的使用

来源的出处、个人数据的处理和法律条件是不同的问题。处理中的角色、保留期限、服务商和合同条件以当前已公布的政策为准。本技术指南不增加新的数据保留承诺，也不证明符合法律法规。

只发送您的工作流程需要的数据。保留置信度类型和未知结果，不要把预测表述为本人自述的身份。不要把推断出的性别作为对个人有重大影响的决策依据。

- [隐私政策](https://www.genderapi.io/zh/privacy-policy)
- [数据处理协议](https://www.genderapi.io/zh/data-processing-agreement)
- [次级处理方](https://www.genderapi.io/zh/subprocessors)
- [GDPR 信息](https://www.genderapi.io/zh/gdpr-compliance)
- [条款和条件](https://www.genderapi.io/zh/terms)
- [联系 GenderAPI.io](https://www.genderapi.io/zh/contact)

## 准确率依据与变更记录

来源标签说明的是预测路径，而不是预测经过测量的质量。准确率指南介绍了如何区分响应中的值、作答覆盖率、错误，以及可复现评估所需的信息。

| 日期 | 文档版本 | 变更 |
| --- | --- | --- |
| 2026-09-29 | 1.0.0 | 注明日期的 MongoDB 盘点、样本一致性检查、V2 的 source 和 match 字段、AI 处理的局限以及来源目录中剩余空白的中文版本。MongoDB 与 Redis 的一致性基于 GenderAPI.io 于 2026年9月26日作出的确认；独立比较仍待完成。未添加任何准确率百分比或关于来源许可的说法。 |

- [准确率与置信度](https://www.genderapi.io/zh/accuracy-methodology)