置信度能说明什么？
V2 的 confidence 值描述的是单个预测背后的依据。它不衡量整个服务的准确率，也不能确定一个人的性别认同。请把它与 confidence_kind、source 和 sample_count 一起解读。
本指南介绍当前的 V2 响应约定和一项拟议的评估方案。约定测试检查的是响应行为；它们并不是使用独立参考标签的准确率研究。本页的更新日期也不是某次准确率测量的日期。
另有一份日期为 2026年9月26日的数据库概况，针对两个集合分别给出了元数据中的文档数量，以及每个集合中 5,000 条随机选取记录的计数一致性。这些检查并没有把预测与独立的参考标签进行比较，因此不提供任何准确率百分比。
两种置信度，两种含义
一个说明性的计算示例：如果所选记录包含 male = 90、female = 10 和 total = 100，confidence 值就是 0.9。这些虚构的数字不是 GenderAPI.io 的实测结果，也不表示使用这个名字的人中有 90% 认同自己为男性。
这里并不把存储的频次视为独立且具有代表性的观测。AI 给出的值并未依据这些频次进行校准。请不要把这两种类型当作可以互换的概率来比较，也不要在没有评估您自己的使用场景之前采用通用的置信度阈值。
| 响应字段 | 数据集结果 | AI 结果 |
|---|---|---|
source | dataset | ai |
confidence_kind | 返回性别时为 observed_frequency | 返回性别时为 model_reported |
confidence | 返回性别时为存储频次的 max(male, female) / total；频次完全相同时为 null | 返回性别时为模型给出的值，大于 0.5 且不超过 1；否则为 null |
sample_count | 所选记录中存储的总计数；不是评估的样本量 | null；不提供数据集的样本量 |
match | 所选候选项、匹配方式，以及国家/地区专属或全局范围 | method 为 model_inference；name、scope 和 country 为 null |
未知结果、含义不明确的结果与错误
对于数据集结果，没有一个通用的阈值会把较低的置信度拒之门外。AI 响应的验证要求非 null 的值大于 0.5。这是约定中的条件，并不能证明预测的质量。请保留 null，不要把它转换为零置信度或猜测出来的性别类别。
| 结果 | V2 中的行为 | 评估中的处理方式 |
|---|---|---|
| 已识别 | result_status 为 identified，gender 为 male 或 female | 与参考标签比较，并计为已作答的案例 |
| 未知 | gender 和 confidence 为 null；result_status 为 unknown | 把该案例保留在相关案例样本中，并与错误预测分开统计 |
| 数据集中频次相同 | 仅使用数据集时，male 和 female 频次相同会产生 reason: ambiguous；回退可能会用 AI 结果替换它 | 记录最终结果和所选的 AI 模式；不要把含义不明确的情况计为额外的结果 |
| AI 依据不足 | AI 给出的未知结果带有 source: ai 和 reason: insufficient_evidence | 计为 unknown；有效的 JSON 响应并不能证明结果正确 |
| 请求或条目出错 | HTTP 错误和批量请求中单个条目的错误属于操作失败，不是性别标签 | 单独报告错误；公布数量和分母，而不是悄悄省略 |
评估您实际使用的配置
- 把姓名、电子邮箱地址和用户名类型的输入分开。电子邮箱地址和用户名的处理包括候选项提取，因此只针对姓名的研究并不能衡量这一整套处理的表现。
- 把 ai_mode 的 off、fallback 和 always 分开。不使用 forceToGenderize 时，单个请求默认使用 fallback，批量请求默认使用 off。fallback 会先查询数据集，没有返回性别时再使用 AI。汇总后的分数可能会掩盖数据集结果与 AI 结果之间的差异。
- 针对每种支持的输入类型分别评估 forceToGenderize。该选项可能根据昵称推断出关联，即使 name 为 null；别名并不能说明账号持有人的身份。
- 记录是否提供了 country。对于每个候选项，如果存在国家/地区专属记录则优先使用，否则使用全局查询。请检查 match.scope 和 match.country，了解选中的是哪条记录。
- 按国家/地区背景、文字和输入类型报告结果，并给出每个细分中的案例数量。地区关联并不能说明国籍或居住地。
- 在测量单独的测试样本之前，先在您的应用中确定可能使用的置信度阈值。针对每种 confidence_kind，分别公布 API 的原始结果和被阈值排除的响应。
指标与分母的定义
在计划中的评估里，N 是带有参考标签的相关案例数量。A = C + W 是返回了性别的案例数：其中 C 个正确，W 个错误。U 表示未知结果，E 表示在应用事先确定的执行规则之后仍出现的操作错误。每个案例只有一个最终结果时，N = C + W + U + E 成立。请先公布这些数量，再公布百分比。
如果 N = 0，针对整个总体的指标没有定义。不要把未定义的指标公布为 0%。请给出不确定性区间及其计算方法。规模小或不具代表性的细分，不足以支持关于准确率的笼统说法。
| 指标 | 定义 | 已公布的测量 |
|---|---|---|
| 作答覆盖率 | A / N | 未测量 |
| 已作答案例中的准确率 | C / A；A = 0 时未定义 | 未测量 |
| 已作答案例中的错误率 | W / A；A = 0 时未定义 | 未测量 |
| 全部相关案例中的正确回答 | C / N；不要把它当作已作答案例中的准确率 | 未测量 |
| 未知结果率 | U / N；含义不明确的情况可作为 U 的一个子集报告 | 未测量 |
| 操作错误率 | E / N；同时按稳定的错误代码细分错误 | 未测量 |
| 校准 | 分别针对 observed_frequency 和 model_reported，把分数区间与观察到的正确率进行比较；说明区间划分、案例数量和不确定性 | 未测量 |
可复现的评估需要包含哪些内容
不要通过向其他根据姓名判断性别的服务索取预测来制作参考标签。如果没有合适的独立参考，这种比较衡量的是一致程度，而不是经过验证的准确率。如果参考标签与 API 的二元结果不相符，请说明这一局限和评估范围，而不是让人们的标签去迁就 API。
| 组成部分 | 所需信息 | 当前的公开依据 |
|---|---|---|
| 参考总体 | 参考标签的来源及使用权；纳入与排除标准、抽样程序、去重和细分定义 | 此处未发布经过验证的参考数据集 |
| 源数据的隔离 | 重叠与数据泄漏检查；开发阶段的测试数据与独立、单独的评估之间的隔离 | 此处未发布确认隔离的报告 |
| 版本与执行 | 执行日期、确切的 API 版本、数据集快照、使用 AI 时的模型或服务商版本、提示词和请求设置 | 此处未发布已完成评估的版本 |
| 结果 | N、C、W、U、E、每个细分的案例数量、置信区间和校准分析 | 此处未发布任何实测的性能数值 |
| 复现与审核 | 评估代码、可复现的汇总结果、已知局限，以及负责审核的具名人员或团队 | 仅有一份方案；没有已完成的独立评估 |
在结果的局限之内使用它
姓名或昵称与性别之间的关联因语言、国家/地区和人群而异。返回的标签无法确定一个人的性别认同。请保留未知结果，并优先采用本人的自述。不要把推断出的性别作为对个人有重大影响的决策依据。
变更记录
| 日期 | 文档版本 | 变更 |
|---|---|---|
| 2026-09-29 | 1.0.0 | V2 置信度类型、结果来源、未知结果和评估分母的中文版本。未发布新的准确率数值。 |