Skip to main content

JunkBox libs/shared-ai 가이드

1. 역할​

  • shared-ai는 JunkBox 앱의 공통 AI provider 연동 라이브러리임.
  • provider 어댑터, 기능별 라우팅, direct·graph runner, 음성 합성(TTS) 호출, prompt·graph registry, AI 통신 예외 정규화, Hub AI usage log writer를 제공함.
  • 외부 AI 호출은 모두 이 라이브러리를 거쳐 LiteLLM으로 나가며, 허가 예외 목록과 표준의 대상 범위는 docs/junkbox/common/guide-jb-core.md 3.3절이 소유함.
  • Chess 실시간 대국은 shared-ai의 자동 착수나 graph runner를 사용하지 않음. AI 상대의 착수는 Lichess Board API에서 수신하며, 종료 대국 AI 복기는 DirectAiRunner를 사용함.

2. 책임 경계​

  • provider 호출과 기능별 model 선택은 shared-ai 책임임.
  • 라우팅 정책 원본은 Hub master-data의 ai-routing.yml임.
  • 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 단일 컬럼 인덱스는 현재 사용하지 않음. 문서 규모나 검색 계획이 달라지면 인덱스 필요성을 다시 검증함.

3. 사용 규칙​

3.1 LLM 호출과 구조화 응답​

  • 앱은 provider를 직접 생성하지 않고 shared-ai runner 또는 service 경계를 사용함.
  • provider/model은 앱 코드가 아닌 route key와 routing YAML이 결정함.
  • AiRouteConfig.full_model_id는 provider:model을 조합하므로 LiteLLM 경유 로그의 litellm: 접두어를 별도 기준정보에 등록하지 않음.
  • 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을 끔.
  • OpenAI Luna의 공대 구인 분석과 Knowbit 카드·퀴즈·채점 라우트는 reasoning_effort: none을 명시해 추론을 끄고 각 라우트의 temperature를 적용함.
  • DirectAiRequest.max_repair_attempts는 구조화 응답 복구 재시도 횟수이며 기본값은 3임. BizCard 인식은 0으로 지정해 실패를 도메인 상태로 기록함.
  • LiteLLM 응답의 첫 choice finish_reason과 사용량의 출력 토큰 수를 generation 결과로 전달함. 구조화 응답의 JSON 파싱·스키마 검증 오류 detail에도 두 값을 포함해 호출 앱이 출력 한도 도달을 판별할 수 있게 함.
  • BIZCARD_RECOGNITION 로컬·기본·운영 라우트는 LiteLLM openrouter/qwen/qwen3.7-flash 모델과 json_object, reasoning_enabled: false를 사용하고 BIZCARD_RECOGNITION_FALLBACK은 openrouter/google/gemma-4-31b-it와 json_schema를 사용함. 두 라우트의 출력 한도는 1024토큰임. BizCard의 조건부 대체 호출 책임은 BizCard API에 있음.
  • 앱 LLM 라우팅의 모델 구성은 Qwen3.7 Flash, Gemma 4 31B, DeepSeek V4.1 Flash, Qwen 2.5 7B Instruct임.
    • Hub 도구 라우트는 HUB_TOOLS_MD, HUB_TOOLS_BOOKMARK이며 모델 연결은 AI 라우팅 YAML이 소유함.
    • Health 화면의 운동 계획 생성은 health-api 규칙 엔진을 사용함.

구조화 응답 진단​

  • generate_structured_content()는 한 요청의 최초 호출과 모델 보정을 공통 요청 ID와 0부터 시작하는 시도 순번으로 연결함. 성공·실패 사용 로그가 이 두 값을 보존함.
  • 진단은 JSON 파싱과 스키마 검증 결과를 기록함. 호출 앱은 구조화 결과의 연결 정보를 사용해 업무 검증 결과를 보고할 수 있음.
  • 진단 오류에는 허용한 코드와 선언된 필드 경로를 기록함. 배열 위치는 []로 일반화하고 사용자 입력으로 결정되는 키와 응답 본문은 진단에서 제외함.
  • 스키마 식별자는 모듈·기능·출력 모델 이름을 사용함. 프롬프트는 실제 사용한 행의 버전을 기록하고 미확인 버전은 생략함.
  • 진단은 연결할 사용 로그 ID가 있을 때 적재함. 적재 시도는 최대 150 ms로 제한하며 호출자가 마감을 전달하면 100 ms 여유를 두고 줄이거나 생략함. 적재 오류는 원래 결과 또는 예외에 영향을 주지 않음.

3.2 개발 문서 임베딩​

  • 사용자 요청 처리용 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임. 검색어 본문은 기록하지 않고 글자 수만 남기며, 기록 실패는 경고만 출력하고 검색·동기화 결과에 영향을 주지 않음.

3.3 음성 합성과 사용량​

  • 음성 합성은 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과 사용량을 보존함.

4. 관련 문서​

  • 공통 설정과 인증은 docs/junkbox/libs/guide-lib-shared-core.md를 따름.
  • Chess 코칭 반영 계약은 docs/junkbox/apps/guide-apps-chess-api.md를 따름.