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 |
数据库检查说明了什么
数值检查要求 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 选项。样本的抽取未使用固定种子，读取时没有冻结快照，处理时也没有独立的参考标签；它们无法衡量预测准确率、校准或作答覆盖率。
在响应中追踪依据
| 字段 | 含义 | 局限 |
|---|---|---|
input | 重复提交的类型、值和国家/地区背景 | 输入值并不是经过独立验证的身份信息 |
match.name / match.method | 显示所选的候选项，以及它是经过规范化、作为部分或子字符串提取的，还是由模型预测的 | 与某个部分匹配，并不能保证从完整姓名或用户名中提取到了真实的名字 |
match.scope / match.country | 显示所选记录来自国家/地区专属查询还是全局查询 | 提供了国家/地区，并不能保证存在该国家/地区的专属记录 |
sample_count | 所选记录中存储的总计数；AI 预测时为 null | 不一定代表唯一人员、独立收集的观测，或准确率评估的样本量 |
confidence / confidence_kind | 区分根据存储频次计算出的比值与模型给出的值 | 两者都不是关于一个人性别认同的经过验证的概率 |
country / country_source | 返回记录的国家/地区元数据，或 AI 给出的姓名与国家/地区之间的关联（如有） | 不能说明国籍、居住地或经过验证的出身，也不能证明提交的国家/地区得到了匹配 |
输入匹配如何影响结果
数据集查询会规范化文本并从中提取候选项。对于电子邮箱地址，候选项来自 @ 之前的部分；对于用户名，开头可选的 @ 会被去掉。电子邮箱地址和用户名的普通查询还可能检查有限的子字符串。如果有多条候选记录，会选择存储总计数最大的那一条。它可能是与想要的名字不同的部分。
如果提供了国家/地区背景，查询会针对每个候选项检查国家/地区专属记录，不存在时再检查全局记录。最终结果会给出所选的匹配。含义不明确的国家/地区专属记录不会被自动替换为该候选项的全局记录。
普通的 AI 提示词寻找可识别的名字。forceToGenderize 还允许通过个人昵称或别名建立关联：在此模式下，非 null 的性别加上 name: null 是有效的结果。这是不同的预测任务，应分别评估。
数据集查询与 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 |
尚未发布的来源文档
此处未发布经过验证的来源目录。仅凭响应约定和实现行为，无法验证数据的出处、来源的使用权、代表性或标签质量。在对具体来源作出说明之前，需要记录并验证以下信息。
本次文档审查并不判定原始来源是否受许可覆盖，也不判定其是否完整。它说明的是公开可用依据的局限。如果您的使用场景需要评估某个具体来源，请联系 GenderAPI.io。
| 依据 | 所需文档 | 公开状态 |
|---|---|---|
| 出处与使用权 | 具名的来源或发布者、收集时间段、许可或其他有记录的使用依据 | 此处未发布经过验证的目录 |
| 处理历史 | 转换、规范化、去重、汇总，以及任何合成或模型生成的贡献 | 不会体现在 source: dataset 标签中 |
| 人群覆盖 | 国家/地区与文字的覆盖、选取程序、标签定义和有记录的偏差 | 此处未发布经过独立评估的覆盖数据 |
| 时效 | 快照标识、每个来源的更新日期以及相应的更新计划 | V2 响应不包含每条记录的时效信息或快照标识 |
| 质量与更正 | 验证结果、重叠检查、更正与删除的处理，以及审核责任 | 此处未发布按来源划分的审计结果 |
数据保护、处理与负责任的使用
来源的出处、个人数据的处理和法律条件是不同的问题。处理中的角色、保留期限、服务商和合同条件以当前已公布的政策为准。本技术指南不增加新的数据保留承诺，也不证明符合法律法规。
只发送您的工作流程需要的数据。保留置信度类型和未知结果，不要把预测表述为本人自述的身份。不要把推断出的性别作为对个人有重大影响的决策依据。
准确率依据与变更记录
来源标签说明的是预测路径，而不是预测经过测量的质量。准确率指南介绍了如何区分响应中的值、作答覆盖率、错误，以及可复现评估所需的信息。
| 日期 | 文档版本 | 变更 |
|---|---|---|
| 2026-09-29 | 1.0.0 | 注明日期的 MongoDB 盘点、样本一致性检查、V2 的 source 和 match 字段、AI 处理的局限以及来源目录中剩余空白的中文版本。MongoDB 与 Redis 的一致性基于 GenderAPI.io 于 2026年9月26日作出的确认；独立比较仍待完成。未添加任何准确率百分比或关于来源许可的说法。 |