봇제작자를 위한 🧩보조모델 에셋 구동 가이드 V3.MD (17495792

RISUAI · AUX ASSET DELEGATION
Asset Delegation Guide
메인 모델은 이야기를 쓰고, 보조 모델은 그림을 단다
v3 · 2026 · CANISTER · 두 모델 위임 패턴
동방환유기(東方幻遊記 · 163 캐릭터)를 만들며
실전에서 다듬은 판본입니다.
FIRST READ · 먼저 읽기
이 md 파일은 당신이 읽으라고 만든 게 아닙니다
아래 설명이 어려워 보여도 괜찮습니다.
이 md는 사람이 아니라
AI에게 건네는 파일
이니까요.
md 파일을 받아 LLM에 첨부하고,
만들려는 봇 이야기만 들려주면 됩니다.
나머지는 가이드를 읽은 LLM이 알아서 합니다.
당신이 Lua를 직접 이해할 필요는 없습니다.
STEP 01
받기
맨 아래 DOWNLOAD에서 md 파일을 내려받습니다.
STEP 02
첨부
Claude · GPT · Codex 등 코딩이 되는 LLM이면 무엇이든 좋습니다. 거기에 md를 붙입니다.
STEP 03
설명
캐릭터와 에셋 목록, 원하는 동작을 평소 말투로 알려주고 "가이드대로 만들어줘"라고 하면 됩니다.
예시 — "이 md 첨부했어. 우리 봇은 캐릭터 A·B가 있고 SFW 표정은 default·smile·angry야. 가이드대로 보조모델 에셋 모듈을 만들어줘."
— ⅰ —
무엇을 위임하는가
두 모델로 나눈다
캐릭터 봇은 대사 사이사이에
인물의 표정 그림이나 상태창을 끼워 넣고 싶어 합니다.
그런데 이 일을, 이야기를 쓰는 메인 모델에게
함께 시키면 자주 어긋납니다.
메인 모델에게 직접 시키면 생기는 일
▷  엉뚱한 캐릭터, 엉뚱한 표정이 나온다
▷  아예 태그를 빼먹는다
▷  목록에 없는 표정 이름을 지어낸다(환각)
▷  "태그 다는 법" 설명이 매 턴 프롬프트를 부풀린다
그래서 역할을 나눕니다.
메인 모델은
이야기와 대사만
씁니다.
그 글을 보조 모델(axLLM)이 다시 읽고,
후처리 단계에서
그림 태그만
JSON으로 끼워 넣습니다.
이야기를 쓰는 자유와 태그를 다는 정확함을,
모델마다 따로 조일 수 있습니다.
— ⅱ —
v3가 다듬은 것
규모가 드러낸 두 가지
v2는 캐릭터 서넛에서 열 명 남짓한 봇에서 잘 돌았습니다.
그것을 163명짜리 동방환유기에 올리자,
작은 봇에서는 보이지 않던 두 가지가 드러났습니다.
§14 · 성능
전체 로스터를 두 번 훑는 함정
줄마다 도는 검증 함수가 그 안에서 다시 전체 캐릭터를 훑으면, 캐릭터가 많을수록 급격히 느려집니다. 검사 범위를 좁히고, 관련 없으면 곧장 빠져나가게 해서 끊었습니다.
＋ 수치와 원칙
정확히는
O(roster²)
— 리롤 한 번에 약 280만 회였습니다. 그리고 한 가지 원칙:
고치기 전에 먼저 재십시오.
axLLM 호출 시간과 전체 훅 시간을 따로 잽니다. "느린 리롤" 28초 가운데 API는 3초였고, 나머지 25초가 Lua였습니다. 프롬프트부터 줄였다면 헛수고였을 겁니다.
§15 · 정확도
코드는 거부할 뿐, 만들어내지 않는다
캐릭터가 백 명을 넘으면 인물이 섞이고, 엉뚱하게 태그되고, 이상한 그림이 저절로 끼어듭니다. v3의 답은 결정론 코드를 더 쌓는 것이 아니라, 글을 읽은 모델을 더 믿는 쪽이었습니다 — 그 구체적인 원칙을 아래 ⅲ에 풀어 둡니다.
— ⅲ —
정확도의 원칙
글을 읽은 것은 모델이지 코드가 아니다
글을 읽은 것은 모델이지 코드가 아닙니다.
그러니 코드는 모델의 선택을
버릴 수는 있어도,
새로 지어내거나 바꿔치기해서는 안 됩니다.
이 한 문장이 v3 전체를 관통합니다.
여섯 가지로 정리됩니다.
REJECT-ONLY
버릴 수는 있어도 바꾸지 않는다
모델이 고른 태그가 검사에 떨어지면 그냥 버립니다. 다른 태그로 몰래 바꿔치기하지 않습니다.
＋ 왜 그런가
"모델은 X를 골랐는데 Lua가 Y를 내보냈다" — 키워드 매퍼가 짐작으로 바꿔치기하던 이것이 가장 큰 정확도 손실이었습니다. 코드는 거르는 장치일 뿐, 다시 쓰는 펜이 아닙니다.
RESCUE-ONLY
채우되 지어내지 않는다
모델이 하나도 주지 않은 인물에게만 한 개를 채웁니다. 옆 인물 수에 맞춰 균형을 맞추지 않습니다.
＋ 한 가지 함정
이름이 감지됐다는 이유만으로 채우면 안 됩니다.
화제로만 언급되고 실제로는 등장하지 않은 인물이 태그되기 때문입니다. "놓친 참여자"와 "옳게 건너뛴 언급"을 코드는 구분하지 못합니다 — 그 판단은 글을 읽은 모델만 할 수 있으니, 커버리지는 코드가 아니라 프롬프트로 끌어올립니다.
FIRST-SEEN
등장한 순서대로 남긴다
동시에 나온 인물이 상한을 넘으면, 캐릭터 목록 순서가 아니라 지금 이 글에서 먼저 등장한 순서로 살립니다.
＋ 안 그러면
중·후반에 활약하는 인물이 통째로 밀려, 그림이 "중반부터 안 나오는" 일이 생깁니다.
WHOLE-REPLY
앞부분에만 쏠리지 않는다
모델에게 건네는 인물별 발췌를 앞 몇 줄이 아니라 글 전체에서 고르게 뽑습니다.
＋ 왜 그런가
첫머리만 보여주면 모델이 도입부 인물만 태그하고 뒷부분을 비웁니다. 코드로 억지로 메우는 대신, 모델 스스로의 커버리지를 안전하게 끌어올리는 방법입니다.
SIGNATURE
필살기 이름이 곧 증거다
고유 필살기 컷인은 그 기술 이름이 불릴 때만 뜹니다. 캐릭터 이름이 아니라 기술 이름으로 시전자를 확인합니다.
＋ 왜 그런가
정작 그 외침에는 시전자 이름이 빠져 있을 때가 많습니다 — "마스터 스파크!"에 "마리사"는 없으니까요. 그래서 고유 필살기에 한해, 기술 이름 자체를 소유자 증거로 인정합니다.
SELECTIVE ANON
거부를 부르는 이름만 가린다
보조 모델이 거부하는 토큰("child" 등)이 든 이름만 익명화하고, 나머지는 실명을 그대로 둡니다.
＋ 어떻게 가리나
그런 이름만 TARGET_NN으로 바꾸고 나머지는 실명을 유지합니다 — 실명이 줄과 인물을 잇는 데 훨씬 정확하니까요. 판단은 글자 그대로의 토큰 검사와 명시적 허용목록으로 합니다. 저성능 보조 모델은 "개념적 나이" 같은 건 가려내지 못합니다.
이 밖에 다중 신호 게이트, ±1줄 증거창, 별칭 완전성,
죽은 코드(if false), sticky 게이트 잔류 같은 함정은
본문 §9·§15에 함께 담겨 있습니다.
— ⅳ —
v2와 무엇이 다른가
v3는 v2를 그대로 품은 위에 얹은 판본입니다.
아키텍처, 여섯 가지 패턴, 리롤, 스켈레톤을 다루는
§1~13은 한 줄도 바뀌지 않았습니다.
성능(§14)과 정확도(§15)가 더해졌을 뿐, 덜어낸 건 없습니다.
·  수십에서 백 단위 캐릭터, 자동 매칭, 검증기를 다루는
큰 봇
이라면 v3 전체가 답입니다.
· 두세 명에서 다섯 명, 단발 시나리오 같은
작은 봇
이라면 v2만으로 충분합니다. 다만 "모델이 권위자, 코드는 거부와 구제만"이라는 §15의 태도는 작은 봇에도 가져갈 가치가 있습니다.
· 치르는 비용은 둘뿐입니다 — 늘어난
분량
과,
큰 규모를 전제
한다는 점. 작은 모듈에 §14까지 통째로 얹는 건 과한 설계입니다. 그 규모에서 실제로 아픈 것만 골라 쓰십시오.
FULL GUIDE · LLM 참조용 전문
전체 가이드
여기부터는 LLM이 읽는 전체 문서입니다.
각 장을 눌러 펼치면 상세 설명과 코드가 나옵니다.
이 문서는 RisuAI 모듈에서
두 모델 에셋 위임 패턴
을 다루는 정본 레퍼런스입니다. 봇별로 일회성으로 작성된 코드보다 여기에 정리된 간결한 패턴을 우선하십시오.
Changelog (v2 → v3)
대규모 로스터 봇(Touhou Genyuuki, 163 캐릭터)을 대상으로 한 하드닝 작업입니다. v3는 규모가 커질 때만 드러나는
성능/프로파일링
과
정확도
규율을 추가합니다:
신규 §14 Performance & profiling
—
O(roster²)
증거 스캔 함정(전체 캐릭터 로스터를 도는 줄별 함수가 또 다른 전체 로스터 루프 안에 중첩되는 경우)과 이를 제거하는 방법: 패치 소유자 범위로 한정한 스캔 + 관련 패치가 없을 때의 빠른 경로(fast path). 그리고
최적화 전에 측정하라
는 규칙:
os.time()
을 후크 전체와는 별개로
axLLM
호출
주위에
계측하십시오 — "느린 리롤"이 전체 28초였지만 API는 3초에 불과했고, 나머지 25초는 Lua CPU였습니다. 따라서 (그럴듯해 보이는 수정인