AI 프롬프트 저장·조회·캐시는 shared-core.masterdata.PromptService와 Hub가 소유함. SharedAiService는 공통 DB 지침을 조회·렌더링해 provider 요청에 전달하며 provider는 전달받은 문자열만 사용함. 전체 관리 범위는 common/guide-jb-common-master-data.md 8.3절을 따름.
Hub 외부 앱의 usage log 기록은 HubApiAiUsageLogWriter가 Hub internal API로 전달함. 외부 앱은 Hub SQLite를 직접 열지 않음.
모델 등록·단가·호출별 비용 계산은 LiteLLM이 소유함. shared-ai는 LiteLLM 비용을 수집해 Hub 사용 로그에 전달하며 AI_MODEL 공통코드 조회나 자체 단가 계산을 수행하지 않음.
개발 문서 벡터 캐시 유틸은 런타임 요청 경로와 분리되어 있으며, scripts/.env.ai와 scripts/sync_dev_docs.py, scripts/search_dev_docs.py가 사용함.
벡터 캐시의 vault.docs는 nullable deleted_at으로 검색 대상 여부를 관리함. 원본에서 사라진 문서는 시각을 기록해 검색에서 제외하고, 같은 경로가 다시 들어오면 deleted_at=NULL로 복원함. source_path 고유 인덱스와 문서 PK는 유지하며, 삭제 시각 단독 인덱스나 namespace·kind·project 단일 컬럼 인덱스는 현재 사용하지 않음. 문서 규모나 검색 계획이 달라지면 인덱스 필요성을 다시 검증함.
LiteLlmProvider는 응답 본문의 usage에서 입력·출력·총 토큰을 읽고 x-litellm-response-cost 헤더를 Decimal로 해석해 AiProviderResponse.response_cost에 전달함. SharedAiService는 이 값을 로그의 est_cost에 저장함.
비용 헤더 누락·빈 값·변환 실패·NaN·무한대·음수는 미산정인 None으로 처리하며 정상적인 0은 보존함. 실패·타임아웃 경로도 est_cost=None을 기록하고 비용이 없었다고 단정하지 않음. 과거 로그는 재계산하지 않음.
direct runner는 선택적 image_data_url을 받아 LiteLLM 사용자 메시지의 이미지 입력으로 전달함. 사용 로그에는 이미지 포함 여부만 기록하고 base64 이미지 본문을 기록하지 않음.
structured_output_mode=json_object는 response_format={"type":"json_object"}를 사용하고, 전달받은 JSON Schema를 시스템 프롬프트에 포함함. JSON Schema를 네이티브로 강제하지 않는 모델도 동일한 필드 계약을 안내받으며 응답의 최종 검증은 공통 Pydantic 계층이 수행함. json_schema 모드는 네이티브 JSON Schema와 strict: true를 사용함.
공통 JSON 출력 지침은 SHARED_AI_JSON_OBJECT_INSTRUCTION이며 schema 변수를 사용함. 스키마 fallback 추가 지침은 SHARED_AI_SCHEMA_FALLBACK_SYSTEM, SHARED_AI_SCHEMA_FALLBACK_USER임.
구조화 응답 재생성은 SHARED_AI_STRUCTURED_REPAIR_USER_TEMPLATE을 사용하며 변수는 original_prompt, error_message, error_details, invalid_response임. 필요한 지침의 조회 실패는 모델 호출을 진행하지 않는 오류임.
AiRouteConfig.reasoning_enabled는 선택적인 추론 제어 설정이며 기본값은 None임. 라우팅 YAML의 값은 SharedAiService와 AiProviderRequest를 거쳐 LiteLLM 요청의 extra_body.reasoning.enabled로 전달됨. false를 명시하면 추론을 끄며, 설정을 생략하면 해당 옵션을 요청에 추가하지 않고 provider 기본 동작을 유지함.
AiRouteConfig.reasoning_effort는 선택적인 추론 강도를 LiteLLM 요청에 전달함. Chess 복기 라우트는 low를 사용함. Chess는 한 배치의 모델 호출에 900초 시간 예산을 적용하며 재요청에는 남은 시간을 사용함. JSON Schema 및 추론 옵션의 provider fallback을 끔.
사용자 요청 처리용 AI 런타임과 개발 문서 검색·동기화는 서로 다른 설정과 실행 경로를 사용함.
개발 문서 검색·동기화는 scripts/.env.ai의 임베딩 설정을 사용하며 현재 LiteLLM 모델명은 openai/openai/text-embedding-3-small임. 이 모델은 앱 LLM 라우팅과 별개의 임베딩 모델이며 문서 검색·색인에 필요함. API 키와 base URL, 모델명은 설정에서 읽고 소스에 비밀 값을 저장하지 않음. 기본 base URL도 LiteLLM proxy임.
임베딩 호출은 실행 1회(동기화 1회, 검색 1회)를 사용 로그 1행으로 합산해 Hub의 AI 전용 엔드포인트 POST /api/v1/master/ai-usage-logs로 기록함. 모듈은 VAULT, 기능은 DOCS_EMBEDDING_SYNC·DOCS_EMBEDDING_SEARCH임. 검색어 본문은 기록하지 않고 글자 수만 남기며, 기록 실패는 경고만 출력하고 검색·동기화 결과에 영향을 주지 않음.
음성 합성은 SharedAiService.synthesize_speech가 LiteLLM POST /audio/speech를 호출함. voice는 공급자 음성 객체(languageCode, name)이고 audioConfig.audioEncoding을 항상 함께 보냄. 429·5xx만 2회 재시도하며 타임아웃·응답 끊김은 재시도하지 않고 과금 여부를 알 수 없는 UNKNOWN으로 남김.
사용 로그는 토큰이 아닌 과금 단위를 usage_unit(예: CHARACTER), usage_quantity, usage_status(RESERVED·SUCCEEDED·FAILED·UNKNOWN) 컬럼으로 표현함. 토큰 과금 호출은 세 컬럼이 NULL이거나 usage_status만 가짐. TTS 로그는 호출 1건당 1행이며 본문 텍스트와 오디오를 기록하지 않고 음성·구간 키·작업 ID만 input_params에 남김.
월 상한이 필요한 호출은 AiSpeechSpec.monthly_limit을 지정함. 호출 전에 같은 모듈·기능의 KST 당월 usage_quantity(RESERVED·SUCCEEDED·UNKNOWN 합산) 검사와 RESERVED 행 삽입을 한 쓰기 트랜잭션(BEGIN IMMEDIATE)으로 처리해 동시 호출에도 상한을 넘지 않음.
상한을 초과하면 공급자를 호출하지 않고 409 월간 사용량 상한을 초과합니다.를 반환함. 호출이 끝나면 같은 행을 결과 상태·비용으로 갱신하며, monthly_limit을 생략하면 호출 후 1행만 기록함.
동시 호출이 세션을 공유하지 않도록 Hub 내부 호출은 PooledAiUsageLogWriter를, 다른 앱은 Hub 내부 API(/ai-usage-logs/reservations, /ai-usage-logs/{usage_log_id})를 쓰는 HubApiAiUsageLogWriter를 사용함.
월 사용량 조회는 month_usage_quantity를 사용하며 화면 표시와 상한 검사가 같은 집계를 공유함.
Chess AI 복기는 Hub usage log와 Chess 복기 초안에 호출 사용량을 기록함. HTTP 200 응답에 최종 본문이 비어 있어도 finish reason과 사용량을 보존함.