README.md

metadata

title: PersonaChatEngine Ai Server
emoji: 👀
colorFrom: green
colorTo: green
sdk: docker
pinned: false
license: mit

⚙️ AI 서버 (ai_server/)

역할 & 데이터 흐름

1. 게임 서버 요청 수신(app.py)

   • 최소 입력만 와도 동작: { text, npc_id, player_id, ... }
   • 옵션: 상태/컨텍스트 부족 시 rag/docs/npc_config.json 등에서 NPC 메타를 조회해 보강

2. 전처리·프롬프트 구성(pipeline/preprocess.py, utils/context_parser.py, manager/prompt_builder.py)

   • 태그/컨텍스트/플레이어 발화를 묶어 <SYS>, <CTX>, <PLAYER>, <NPC> 포맷으로 구성

3. 추론 요청(utils/hf_client.py, models/fallback_model.py, pipeline/generator.py)

   • 조건 불충족 input → fallback_model.py에서 대체 응답 생성
   • 조건 충족 input → generator.py에서 payload 구성 후 HF Space /predict_main POST

4. 후처리(pipeline/postprocess.py)

   • 모델 응답에서 대사 텍스트, delta, flag를 파싱·정규화
   • flags → 시그모이드+threshold, delta → 범위 클램프·라운딩

5. 게임 서버 응답(schemas.py)

   • 표준 JSON으로 반환

   {
     "text": "NPC의 대답...",
     "delta": {"trust": 0.10, "relationship": 0.08},
     "flags": {"give_item": true, "npc_main_story": false},
     "meta": {"npc_id": "mother_abandoned_factory"}
   }
   

---

📁 디렉토리 구조

ai-server/
├── app.py                  # FastAPI 엔트리포인트
├── config.py               # 서버 설정 및 모델 경로 관리
├── schemas.py              # 요청/응답 데이터 구조 정의
├── requirements.txt        # 의존성 패키지 목록
├── pipeline/               # 대화 흐름 처리 모듈
│   ├── preprocess.py       # 입력 전처리 및 프롬프트 구성
│   ├── postprocess.py      # 모델 출력 후처리
│   └── generator.py        # 모델 추론 요청 처리
├── rag/                    # RAG 기반 flag 해석 모듈
│   ├── rag_manager.py
│   └── docs/npc_config.json
├── utils/                  # 유틸리티 모듈
│   ├── hf_client.py        # HF API 통신
│   └── context_parser.py   # 대화 맥락 파싱
├── models/                 # 모델 로딩 및 fallback 처리
│   ├── emotion_model.py    # emotion model을 이용한 inference 진행
│   ├── fallback_model.py   # fallback model을 이용한 inference 진행
│   └── model_loader.py
└── manager/
    ├── agent_manager.py    
    ├── dialogue_manager.py # 전체 pipeline 모듈 관리
    └── prompt_builder.py

---

🧩 최신 RAG 타입별 매핑 (11종)

type	조회 시점	조회 조건	사용 모듈/함수	주요 목적
trigger_def	preprocess_input	npc_id, quest_stage	retrieve(...)	메인 경로 조건 판정
fallback	preprocess_input	npc_id, quest_stage	retrieve(...)	fallback prompt 구성
forbidden_trigger_list	preprocess_input	npc_id	_load_forbidden_trigger_data	금지 트리거 감지
trigger_meta	preprocess_input	npc_id, trigger	_load_trigger_meta	특수 fallback 시 delta/action 확정
lore	build_main_prompt	npc_id, quest_stage/any	RAG main docs	세계관/배경 설명
description	build_main_prompt	npc_id, quest_stage	RAG main docs	현재 상황 설명
flag_def	postprocess_pipeline	npc_id, quest_stage, flag_name	pre_data["rag_main_docs"]	flag threshold/예시 문장
main_res_validate	postprocess_pipeline	npc_id, quest_stage	pre_data["rag_main_docs"]	응답 검증 기준
npc_persona	build_main_prompt	npc_id	retrieve(...)	NPC 성격·특성 반영
dialogue_turn	postprocess_pipeline	npc_id, quest_stage	retrieve(...)	대화 예시 참조
(없음)	fallback_final_check	pre_data["trigger_meta"]	-	응답 의미 일치 검증

---

📌 데이터 흐름 요약

1. preprocess_input()

   • trigger_def → 메인 조건 판정
   • forbidden_trigger_list + trigger_meta → 특수 fallback 감지
   • fallback → 일반 fallback 스타일

2. build_main_prompt()

   • lore + description + npc_persona → 메인 prompt 컨텍스트 구성

3. build_fallback_prompt()

   • fallback_style + trigger_meta → fallback prompt 구성

4. postprocess_pipeline()

   • flag_def → flag threshold/예시
   • main_res_validate → 응답 검증

5. fallback_final_check()

   • trigger_meta → delta/action 의미 일치 검증

---

🔗 테스트

업데이트 예정

---

👀 PersonaChatEngine AI Server

게임 내 NPC 대화 엔진 API 서버입니다.
최소 입력만으로도 동작하며, RAG 기반 문서와 NPC 메타데이터를 활용해 대화를 보강합니다.

⚙️ 주요 기능

• 게임 서버 요청 수신 및 전처리
• 조건 판정 후 메인/폴백 모델 추론
• RAG 기반 세계관·상황·NPC 성격 반영
• 응답 후처리 및 JSON 표준 응답 반환

---