AI 기능 레지스트리 (규격 초안)
작성: 2026-09-14 · 상태: 초안 — docs/DECISION_LOG.md(2026-09-14) · docs/MODEL_GATEWAY_SCOPE.md §9 결정에 따른 규격
1. 목적
AI를 사용하는 공통기능을 고정 목록이 아니라 열린 목록으로 등록·연결·관측하는 단일 규격을 정의한다. 새 기능 추가는 서비스 코드·스키마·화면 변경이 아니라 등록 한 건으로 끝나야 한다.
기능은 계속 늘어난다 — 요약·번역·정합성 → 영역 추론, 검색 → RAG → 실시간 번역. 기능을 enum(["search","answer"] 같은)으로 고정하면 확장마다 여러 저장소를 함께 고쳐야 하고, 화면을 서비스별로 만들면 관리자가 여러 곳을 오가며 "어느 포털에 어떤 AI 기능이 적용됐는지" 볼 지점이 사라진다.
2. 개념
| 개념 | 정의 | 소유자 |
|---|---|---|
| AI 기능(Feature) | 포털이 사용하는 AI 단위 기능. purposeId로 귀속·집계된다 | 등록·정책은 PortalConsole, 업무 규칙(프롬프트·적용 범위)은 각 포털 |
| 능력(Capability) | 기능이 요구하는 실행 능력(completion·retrieval·streaming·embedding·tool_use 등) | 충족은 각 플랫폼 서비스 |
| 연결(Wiring) | 기능이 실제로 붙는 대상 — model(ModelGateway) · retrieval(ExploreGateway·RagService) | 각 플랫폼 서비스 |
| 정책(Policy) | 적용 여부 · 쿼터(포털×purpose) · 허용 모델 | PortalConsole(제어평면) |
| 관측(Observation) | 사용량·지연·실패율 | 각 서비스가 집계, 콘솔이 표시 |
핵심은 "기능"과 "능력"의 분리다. 기능은 업무 단위(실시간 번역)이고, 능력은 실행 조건(streaming)이다. 능력이 아직 준비되지 않았으면 기능은 오류가 아니라 "준비 중" 이다.
3. 기능 레코드 스키마 (초안)
| 필드 | 형 | 설명 |
|---|---|---|
featureId | string | 기능 식별자(예: process.version-summary) |
portalId | string | 등록 포털. 플랫폼 공통 제공이면 platform |
label | string | 표시 이름(예: 영역 추론, 실시간 번역) |
purposeId | string | 귀속·집계 단위 — ModelGateway x-purpose와 동일 어휘(예: process.version-summary) |
capabilities | string[] | 요구 능력 — completion · retrieval · streaming · embedding · tool_use |
wiring.model | { provider, model } | null | ModelGateway 연결(완성). completion 능력이면 필수 |
wiring.retrieval | { source, index } | null | ExploreGateway·RagService 연결(선택). RAG 기능이면 사용 |
policy.enabled | boolean | 적용 여부 |
policy.quota | { window, limit } | null | 포털×purpose 한도(MODEL_GATEWAY_SCOPE §8-6과 정렬) |
observation | 요약 | 최근 사용량·지연·실패 — 파생 값(저장 대상 아님) |
예 — 요약(비스트리밍 완성)
jsonc
{
"featureId": "process.version-summary",
"portalId": "process-center",
"label": "게시본 요약",
"purposeId": "process.version-summary",
"capabilities": ["completion"],
"wiring": { "model": { "provider": "deepseek", "model": "deepseek-flash" }, "retrieval": null },
"policy": { "enabled": true, "quota": { "window": "day", "limit": 200000 } }
}예 — RAG(완성 + 검색 연결)
jsonc
{
"featureId": "process.manual-answer",
"portalId": "process-center",
"label": "매뉴얼 근거 답변",
"purposeId": "process.manual-answer",
"capabilities": ["retrieval", "completion"],
"wiring": {
"model": { "provider": "deepseek", "model": "deepseek-flash" },
"retrieval": { "source": "process-center", "index": "manuals" }
},
"policy": { "enabled": true, "quota": { "window": "day", "limit": 200000 } }
}예 — 실시간 번역(능력 미비 → 준비 중)
jsonc
{
"featureId": "guide.live-translate",
"portalId": "guide-center",
"label": "실시간 번역",
"purposeId": "guide.live-translate",
"capabilities": ["completion", "streaming"],
"wiring": { "model": { "provider": "openai", "model": "gpt-4o-mini" }, "retrieval": null },
"policy": { "enabled": false }
}4. 능력 ↔ 서비스 매트릭스
| 능력 | 충족 서비스 | 현재 상태 |
|---|---|---|
completion | ModelGateway | ✅ 제공 |
embedding | ModelGateway(x-purpose: rag.embedding) | ✅ 제공 |
retrieval | ExploreGateway(탐색 조합) · RagService(색인·RAG·citation) | ✅ 경계 확정(2026-09-15, SEARCH_SCOPE.md) — 콘솔 관리·상태 API 계약 초안 있음(연결은 서비스 가용 후) |
streaming | ModelGateway | ⛔ 보류(MODEL_GATEWAY_SCOPE §8-8) — 실시간 번역 등 도입 시 재개 |
tool_use | (미정) | — |
기능을 등록할 때 요구 능력이 이 표에서 준비 상태인지 먼저 확인한다. 미비하면 policy.enabled=false(준비 중)로 두고, 능력 자체를 서비스 로드맵 항목으로 올린다.
플랫폼이 제공하는 AI 기능(자체 purpose) — 2026-09-14 온톨로지 확정(ONTOLOGY_SCOPE.md)에 따라 등록 대상:
| 기능 | purposeId | 능력 | 상태 |
|---|---|---|---|
| 온톨로지 후보 추출(개념·관계·용어) | ontology.extract | completion(+ retrieval) | ⏳ 구현 예정 — 결과는 proposed이며 사람 승인 전에는 색인에 반영하지 않는다 |
| 온톨로지 관계 후보 제안 | ontology.link | completion | 조건부 — 추출 품질이 안정된 뒤 |
이 두 기능의 결과는 제안이고, 승인 절차(사람)를 거친 것만 지식으로 쓰인다. 범위 판정 기준과 관계 유형 7종은 ONTOLOGY_SCOPE.md.
5. 소유 경계
| 대상 | 소유자 |
|---|---|
| 기능의 업무 규칙(무엇을 요약·번역할지, 프롬프트 내용) | 각 소비 포털 (MODEL_GATEWAY_SCOPE §3 · §8-1) |
| 기능의 등록·허용·쿼터·적용 현황(운영 표면) | PortalConsole(제어평면) |
| 기능의 실행 연결(모델·키·색인·검색) | ModelGateway · ExploreGateway · RagService |
| 기능의 재사용 구현·계약·패턴 | portal-foundation(@hohyun94/portal-ai) — 2026-08-20 "공통 기능은 Asset 제공" |
- PortalConsole은 모델·키·색인·검색 실행을 소유하지 않는다(표시·정책·프록시만).
- 게이트웨이는 UI를 갖지 않는다(
MODEL_GATEWAY_SCOPE§8-7). 콘솔 서버가 서버 간 토큰으로 각 서비스 관리 API를 호출한다. - RAG는 ModelGateway 소유가 아니다. RAG 기능은
wiring.model + wiring.retrieval을 함께 가진 기능으로 기록한다.
6. 콘솔 표면(뷰 3개)
| 뷰 | 내용 | 데이터 출처 |
|---|---|---|
| 적용 현황 | 포털 × 기능 매트릭스 — 적용 / 준비 중(능력 미비) / 미사용, 연결 모델·색인 | 레지스트리 + 각 서비스 상태 API |
| 사용량 | 포털 × 기능 — 완성 토큰·요청·실패·지연 + 검색·색인 지표 | ModelGateway /admin/api/usage, RagService·ExploreGateway 상태 API |
| 세팅 | 기능별 연결(모델·키·쿼터), 서비스별 세팅(프로바이더·키·색인·검색 조합) | 각 서비스 관리 API(서버 간 프록시) |
7. 새 기능 추가 절차
- 등록 —
featureId·purposeId·label·capabilities를 정해 등록한다(콘솔). - 능력 확인 — §4 매트릭스에서 요구 능력의 준비 상태를 확인한다. 미비하면
enabled=false(준비 중). - 연결 —
wiring.model(완성, 필수) ·wiring.retrieval(RAG일 때). - 정책 — 활성화 + 쿼터 설정. 이후 사용량이
purposeId기준으로 자동 집계된다.
목표는 코드 변경 없는 확장이다. 능력 자체가 없어 코드 변경이 필요하면 그건 서비스 로드맵 항목이다(예: ModelGateway 스트리밍 재개).
8. 후속(미해결)
| # | 항목 | 상태 |
|---|---|---|
| 1 | 포털 카탈로그의 고정 capabilities(["search","answer"]) → 이 레지스트리로 승격 | 미착수 |
| 2 | RagService ↔ ExploreGateway 경계(권장 A안) 확정 | ✅ 확정(2026-09-15, SEARCH_SCOPE.md) |
| 3 | RagService·ExploreGateway의 콘솔용 관리·상태 API 계약 | ⏳ 초안 완료(SEARCH_SCOPE.md §6) — 실제 연결은 서비스 가용 후 |
| 4 | ModelGateway 스트리밍 재개(실시간 번역 등 스트리밍 기능 도입 시) | 조건부 |
| 5 | 레지스트리 저장 위치(콘솔 DB 테이블 vs 환경 설정) 확정 | 미착수 |