V2에서 source는 무엇을 뜻하나요?
source 필드는 최종 결과를 만든 경로를 나타냅니다. 저장된 데이터셋 조회, AI 추정, 선택된 출처 없음 중 하나입니다. 데이터셋의 원래 발행처에 대한 인용, 라이선스 증명, 추정이 맞다는 보증이 아닙니다.
이 가이드는 현재 V2 응답 규격과 GenderAPI.io가 직접 작성한 데이터베이스 프로필을 설명합니다. 아래의 관찰은 측정된 건수 집계와 일관성 확인입니다. 검토된 원천 출처 카탈로그와 독립적인 정확도 측정은 아직 게시되지 않았습니다.
| source | 알려 주는 것 | 확정하지 않는 것 |
|---|---|---|
dataset | 저장된 행이 선택되었습니다. 건수가 정확히 같으면 성별이 알 수 없음으로 반환될 수 있습니다 | 원래 발행처, 수집 방법, 라이선스, 행이 만들어진 시기, 관찰의 독립성 |
ai | 최종 응답이 설정된 AI 추정 경로에서 나왔습니다. 성별은 여전히 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 건수가 유한하며 0과 total 사이에 있을 것을 요구합니다. 별도의 확인에서는 male + female을 total과 비교합니다. 표본의 모든 카운터가 이 확인을 통과했습니다. 이것이 컬렉션의 모든 행이 일관적이라거나 어떤 추정이 맞다는 주장은 아닙니다.
male과 female 건수가 같은 경우는 일반 컬렉션 표본에서 124행, 국가별 컬렉션 표본에서 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는 개인의 별명이나 별칭을 통한 연관성도 허용하므로, 이 모드에서는 name: null과 함께 null이 아닌 성별이 반환되어도 유효합니다. 이는 서로 다른 추정 작업이므로 따로 평가해야 합니다.
데이터셋 조회와 AI 처리
AI가 사용되면 V2는 제출한 type, value와 국가 컨텍스트를 AI 추정용으로 설정된 서비스에 보냅니다. 이메일 주소 입력의 경우 프롬프트는 모델에게 도메인과 플러스 기호 뒤의 접미사를 무시하도록 지시합니다. 이는 AI가 처리하기 전에 해당 문자가 값에서 제거된다는 약속이 아닙니다. 워크플로에 데이터셋 전용 추정이 필요하면 forceToGenderize 없이 ai_mode: off를 사용하세요.
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가 같다는 판단은 2026년 9월 26일 GenderAPI.io의 확인에 근거하며, 독립적인 비교는 아직 남아 있습니다. 정확도 백분율이나 출처 라이선스에 관한 주장은 새로 추가하지 않습니다. |