korean-people-persona

Conjunto de herramientas para convertir y buscar el conjunto de datos de HuggingFace nvidia/Nemotron-Personas-Korea (aprox. 1 millón de filas, 9 archivos parquet) en SQLite.

Resumen

• Fuente: NVIDIA, Nemotron-Personas-Korea — https://huggingface.co/datasets/nvidia/Nemotron-Personas-Korea

• Licencia: Sigue los términos de licencia de la página original del conjunto de datos

• Archivo DB: database/persona.db

• Parquet original: data/train-*-of-*.parquet

• Tablas: persona (principal) + persona_fts (índice de contenido externo FTS5)

• SQLite objetivo: 3.37+ (usa FTS5, tablas STRICT, JSON1)

• Python: 3.10 o superior (se recomienda 3.11+)

• Dependencias: pyarrow >= 15.0, huggingface_hub >= 0.24 (ver requirements.txt)

• Espacio en disco: aprox. 5 GB (parquet ~2GB + DB ~3GB)

Related MCP server: @nahisaho/katashiro-mcp-server

Fuente de datos

Estructura de carpetas

korean-people-persona/
├── data/ # 원본 parquet (gitignore — 약 2GB)
│ └── train-*-of-*.parquet
├── database/ # 생성된 SQLite (gitignore — 약 3GB)
│ └── persona.db
├── src/
│ ├── convert/ # parquet → SQLite 변환기
│ │ ├── __init__.py
│ │ └── __main__.py
│ └── mcp_server/ # (예정) MCP 서버
├── build.sh / build.bat / build.ps1
├── requirements.txt
└── README.md

data/ y database/ se excluyen mediante .gitignore debido a su gran tamaño.

Descarga del conjunto de datos

Elija uno de los tres métodos. El archivo resultante debe ubicarse en la carpeta data/ con el formato train-*-of-*.parquet.

1) Opción de script de conversión (recomendado)

El paquete src/convert descarga automáticamente si falta:

pip install huggingface_hub pyarrow
PYTHONPATH=src python -m convert --download # 없을 때만 받음
PYTHONPATH=src python -m convert --download --force-download # 항상 재다운로드

2) Uso directo de huggingface-cli

pip install huggingface_hub
huggingface-cli download nvidia/Nemotron-Personas-Korea \
 --repo-type dataset \
 --include "train-*-of-*.parquet" \
 --local-dir ./data

3) Clonación con git lfs

git lfs install
git clone https://huggingface.co/datasets/nvidia/Nemotron-Personas-Korea
mv Nemotron-Personas-Korea/train-*.parquet ./data/

Autenticación: Para modelos privados o restringidos, se requiere huggingface-cli login o la variable de entorno HF_TOKEN. Este conjunto de datos (al momento de su publicación) se puede descargar sin autenticación.

Capacidad: Total de 9 archivos parquet aprox. 1~2 GB.

Tabla principal persona

CREATE TABLE persona (
 uuid TEXT PRIMARY KEY, -- 32자 hex 문자열 (대시 없음)
 -- 페르소나 서술 (긴 한국어 텍스트) ----------------------------------------------
 persona TEXT NOT NULL, -- 핵심 1~2문장 요약
 professional_persona TEXT NOT NULL, -- 직업/업무 페르소나
 sports_persona TEXT NOT NULL, -- 스포츠/운동 페르소나
 arts_persona TEXT NOT NULL, -- 예술/문화 페르소나
 travel_persona TEXT NOT NULL, -- 여행 페르소나
 culinary_persona TEXT NOT NULL, -- 식문화/요리 페르소나
 family_persona TEXT NOT NULL, -- 가족 관계 페르소나
 cultural_background TEXT NOT NULL, -- 문화·성장 배경 서술
 skills_and_expertise TEXT NOT NULL, -- 보유 기술/전문성 서술
 hobbies_and_interests TEXT NOT NULL, -- 취미·관심사 서술
 career_goals_and_ambitions TEXT NOT NULL, -- 향후 목표/포부
 -- 리스트 (JSON 배열로 저장) -----------------------------------------------------
 skills_and_expertise_list TEXT NOT NULL CHECK(json_valid(skills_and_expertise_list)), -- 스킬 키워드 JSON 배열
 hobbies_and_interests_list TEXT NOT NULL CHECK(json_valid(hobbies_and_interests_list)), -- 취미 키워드 JSON 배열
 -- 인구통계 ---------------------------------------------------------------------
 sex TEXT NOT NULL, -- 성별: 남자 / 여자
 age INTEGER NOT NULL CHECK(age >= 0), -- 나이 (정수)
 marital_status TEXT NOT NULL, -- 결혼상태 (4종: 미혼/기혼/이혼/사별 등)
 military_status TEXT NOT NULL, -- 병역상태 (군필/해당없음 등)
 family_type TEXT NOT NULL, -- 가구 유형 (39종: 1인 가구, 배우자와 자녀 등)
 housing_type TEXT NOT NULL, -- 주거 형태 (6종: 아파트, 단독주택 등)
 education_level TEXT NOT NULL, -- 최종 학력 (7종: 초등학교 ~ 대학원)
 bachelors_field TEXT NOT NULL, -- 학사 전공 분야
 occupation TEXT NOT NULL, -- 직업 (자유 텍스트)
 district TEXT NOT NULL, -- 시군구 (예: 강남-서초)
 province TEXT NOT NULL, -- 시도 (17종)
 country TEXT NOT NULL DEFAULT '대한민국' -- 국가 (단일값: 대한민국)
) STRICT;

Índices

Significado de las columnas

Búsqueda de texto completo — persona_fts (FTS5)

Indexación de 10 columnas largas de descripción en coreano mediante el método de contenido externo.

CREATE VIRTUAL TABLE persona_fts USING fts5(
 professional_persona,
 sports_persona,
 arts_persona,
 travel_persona,
 culinary_persona,
 family_persona,
 cultural_background,
 skills_and_expertise,
 hobbies_and_interests,
 career_goals_and_ambitions,
 content='persona',
 content_rowid='rowid',
 tokenize='unicode61 remove_diacritics 2',
 prefix='2 3 4'
);

Tokenizador: unicode61 + índice de prefijo de 2/3/4 caracteres. Para manejar las partículas coreanas, se recomienda la coincidencia de prefijo en forma de 등산* al buscar. Si se requiere análisis morfológico, reemplazar con un tokenizador personalizado basado en mecab-ko / kiwi.

Sincronización FTS: Dado que el conjunto de datos es estático, se construye una vez con INSERT INTO persona_fts(rowid, ...) SELECT .... Si hay cambios, añadir disparadores (triggers).

Uso de agentes de IA (Servidor MCP)

Este repositorio proporciona un servidor MCP (Model Context Protocol), permitiendo que agentes compatibles con MCP como Claude Desktop, Cursor o Cline busquen y muestren datos directamente.

Ejecución

PYTHONPATH=src python -m mcp_server # stdio 서버 시작

Método de registro por agente

Todos los ejemplos deben cambiar la ruta absoluta del repositorio /abs/path/to/korean-people-persona según su propio entorno. Si ha creado un entorno virtual (.venv), especifique el command como el ejecutable de Python dentro del venv para evitar conflictos de dependencias. (Ej: macOS/Linux /abs/path/.venv/bin/python, Windows C:/abs/path/.venv/Scripts/python.exe)

Claude Desktop

Ubicación del archivo de configuración:

O mediante el menú Settings → Developer → Edit Config dentro de la aplicación.

{
 "mcpServers": {
 "korean-persona": {
 "command": "python",
 "args": ["-m", "mcp_server"],
 "env": {
 "PYTHONPATH": "/abs/path/to/korean-people-persona/src",
 "PYTHONIOENCODING": "utf-8"
 }
 }
 }
}

Después de guardar, reinicie Claude Desktop → verifique que se muestren 5 herramientas en el icono de martillo (🔨) en la parte inferior derecha de la ventana de chat.

Claude Code (CLI)

Registro en una línea mediante comando CLI:

claude mcp add korean-persona python -m mcp_server \
 -e PYTHONPATH=/abs/path/to/korean-people-persona/src \
 -e PYTHONIOENCODING=utf-8

O escríbalo directamente en .mcp.json en la raíz del proyecto / configuración de usuario ~/.claude/settings.json:

{
 "mcpServers": {
 "korean-persona": {
 "command": "python",
 "args": ["-m", "mcp_server"],
 "env": { "PYTHONPATH": "/abs/path/to/korean-people-persona/src" }
 }
 }
}

Verificación: claude mcp list → después de activar, puede llamar a las herramientas con el comando de barra /mcp.

Cursor

.cursor/mcp.json por proyecto o configuración global de usuario ~/.cursor/mcp.json:

{
 "mcpServers": {
 "korean-persona": {
 "command": "python",
 "args": ["-m", "mcp_server"],
 "env": { "PYTHONPATH": "/abs/path/to/korean-people-persona/src" }
 }
 }
}

O use la interfaz Settings → MCP → Add new MCP Server. Después de reiniciar Cursor, llame con @korean-persona.

ChatGPT (Developer Mode / Connectors)

La integración MCP de ChatGPT funciona basada en el transporte HTTP/SSE (conector remoto). Dado que este servidor es un servidor stdio, no se puede registrar tal cual; debe envolverse con un adaptador HTTP para exponerlo.

1. Ejecute el servidor con el transporte HTTP del SDK mcp:

   PYTHONPATH=src python -m mcp_server --transport sse --port 8765

   (Actualmente, server.py en este repositorio solo llama a stdio. Para usar el modo HTTP/SSE, se requiere añadir una bifurcación con mcp.run(transport="sse", port=8765).)

2. Exposición externa mediante ngrok / Cloudflare Tunnel, etc.:

   ngrok http 8765

3. ChatGPT → Settings → Connectors → Developer mode → Add custom connector

   • URL: https://<ngrok>/sse

   • Autenticación: Añadir encabezado de token Bearer si es necesario (MCP_AUTH_TOKEN)

4. En un nuevo chat, active el conector en el menú Tools para poder llamar a las herramientas.

Nota de seguridad: Dado que el conector de ChatGPT expone herramientas fuera del modelo, proteja la URL pública con autenticación. Si es solo para uso local, se recomienda usar Claude Desktop / Cursor basados en stdio.

Gemini CLI

Configuración de usuario de Google gemini-cli ~/.gemini/settings.json:

{
 "mcpServers": {
 "korean-persona": {
 "command": "python",
 "args": ["-m", "mcp_server"],
 "env": { "PYTHONPATH": "/abs/path/to/korean-people-persona/src" },
 "cwd": "/abs/path/to/korean-people-persona"
 }
 }
}

Verificación: gemini mcp list (o comando /mcp dentro de la CLI) → exposición automática de herramientas.

Solución de problemas comunes

Herramientas expuestas

Ejemplos de uso de agentes

1) Simulación de entrevista de marketing

"Muestrea a 10 mujeres mayores de 60 años que disfrutan del senderismo y simula su reacción ante el anuncio de una nueva rodillera lanzada al mercado."

El agente funciona con el siguiente flujo:

1. search_persona(query="등산*", filters={"sex":"여자","age_min":60}, limit=10, full=True)

2. Inyectar cada persona en el prompt del sistema → generar 1 respuesta de evaluación de anuncio por persona

3. Resumir insights después de agrupar las respuestas

2) Casting de personajes basado en la región

"Busca una persona que sea trabajador autónomo de 50 años que viva en Yeongdo-gu, Busan, y organízalo para que pueda usarlo como protagonista de una novela corta."

search_persona(
 filters={"province":"부산", "district_like":"%영도%",
 "age_min":50, "age_max":59,
 "occupation_like":"%자영%"},
 limit=5, full=True
)

3) Análisis de impacto de políticas

"Analiza la distribución de en qué provincia hay más hogares unipersonales de personas mayores de 70 años cuyo nivel educativo final es la escuela primaria."

aggregate(
 group_by=["province"],
 filters={"education_level":"초등학교", "age_min":70,
 "family_type_like":"%혼자%"},
 limit=20
)

4) Búsqueda basada en significado + citas

"Busca una persona que haya crecido en una zona rural y tenga nietos, y avísame junto con una cita de su cultural_background."

search_persona(
 query='"농촌" AND 손주*',
 fields=["cultural_background", "family_persona"],
 limit=5, full=True
)

5) Encuesta sintética

"Realiza un muestreo estratificado de 100 personas proporcional a la distribución de la población nacional y pregúntale a cada una si está a favor de la introducción de la semana laboral de 4 días."

1. aggregate(group_by=["province","sex","age"]) → calcular ratios de distribución

2. Llamar a sample_persona según los ratios por provincia×sexo×grupo de edad

3. Solicitar a la LLM una respuesta 1:1 para cada persona

4. Agregar resultados → calcular la distribución a favor/en contra aplicando ponderaciones

Uso directo (código)

Llamada directa desde Python sin MCP:

import sys; sys.path.insert(0, "src")
from mcp_server import tools

tools.stats()
tools.search_persona(query="용접*", filters={"sex":"남자"}, limit=5)
tools.sample_persona(filters={"province":"제주"}, n=3, full=True)

Consulta SQL directa

-- 1) 등산을 좋아하고 트로트 관련 언급이 있는 60대 여성
SELECT p.uuid, p.age, p.province, p.occupation
FROM persona_fts f
JOIN persona p ON p.rowid = f.rowid
WHERE persona_fts MATCH '등산* AND 트로트*'
 AND p.sex = '여자' AND p.age BETWEEN 60 AND 79
ORDER BY bm25(persona_fts) LIMIT 20;

-- 2) 특정 컬럼 검색 + 스니펫
SELECT p.uuid, snippet(persona_fts, 7, '<b>', '</b>', '...', 10) AS hit
FROM persona_fts f JOIN persona p ON p.rowid = f.rowid
WHERE f.skills_and_expertise MATCH '용접*' LIMIT 10;

-- 3) JSON 리스트 펼치기
SELECT p.uuid, j.value AS hobby
FROM persona p, json_each(p.hobbies_and_interests_list) j
WHERE j.value LIKE '%낚시%' LIMIT 10;

-- 4) 인구통계 분포
SELECT province, sex, COUNT(*) cnt
FROM persona GROUP BY province, sex ORDER BY cnt DESC;

Configuración PRAGMA (carga/operación)

PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;
PRAGMA temp_store = MEMORY;
PRAGMA cache_size = -262144; -- 256MB

Procedimiento de construcción

Construcción en una línea (recomendado)

El script envoltorio por SO realiza automáticamente la creación del entorno virtual → instalación de dependencias → descarga → conversión.

Las opciones de re-descarga se pasan de la misma manera:

./build.sh --force-download
build.bat --force-download
.\build.ps1 --force-download

Si hay un error de política de ejecución en PowerShell: PowerShell -ExecutionPolicy Bypass -File .\build.ps1

Ejecución manual

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows: .venv\Scripts\activate
pip install -r requirements.txt
PYTHONPATH=src python -m convert [--download] [--force-download]

Procesamiento interno:

1. (Opcional) Con --download, descarga los archivos parquet faltantes desde HuggingFace

2. Crea un nuevo persona.db (elimina el archivo existente)

3. Configuración de PRAGMA + creación de esquema/índices

4. Lee secuencialmente los 9 archivos parquet, normaliza por filas y carga mediante executemany (unidad de transacción: 1 archivo)

5. Las columnas *_list se convierten de ast.literal_eval → json.dumps(ensure_ascii=False)

6. Creación de tabla virtual FTS5 + construcción única INSERT ... SELECT

7. Después de INSERT INTO persona_fts(persona_fts) VALUES('optimize'), ejecutar ANALYZE

8. Cierre después del punto de control WAL

Estimación de disco

• Tabla principal + índices: aprox. 1.5 ~ 2.5 GB

• Incluyendo prefijo FTS5: 1 ~ 3 GB adicionales

• Total estimado aprox. 3 ~ 5 GB (actualizado después de la carga real).

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers