Ontology LLM Identifier — M4 Step 1

본 가이드는 Epic #1246 M4 Step 1 에서 도입된 LLM 기반 Ontology Class identifier 를 다룹니다. M3 Step 4 의 substring 매칭은 "재기화 공정 출구 압력" 같은 자연어 질의에 매치 0건 또는 무의미 — LLM 식별로 정밀도 향상.

동작

설정

config.py:

class Settings(BaseSettings):
    llm_anthropic_api_key: str = ""  # Anthropic Claude
    ontology_identifier_method: str = "llm"  # \"llm\" | \"substring\"

env: GEND_LLM_ANTHROPIC_API_KEY, GEND_ONTOLOGY_IDENTIFIER_METHOD.

method=\"substring\" 으로 dev 환경에서 token 절감 가능.

API

`identify_relevant_classes_with_fallback(db, question, *, top_n=5, method=\"llm\")`

hybrid_rag.identify_relevant_classes 의 drop-in replacement. 반환:

(classes: list[OntologyClass], used_method: str)
# used_method ∈ \"llm\" | \"substring\" | \"substring_fallback\"

rag_context.py::assemble_rag_context 가 자동 호출 — RAGContext.ontology_identifier_method 필드로 노출.

`identify_relevant_classes_llm(db, question, *, top_n=5, anthropic_key)`

low-level LLM 호출. 키 미설정 / question 빈 → IdentifierLLMError raise 또는 빈 list.

Prompt 구성

System message (ephemeral cached)

You are an ontology class identification assistant for the GenD data platform.
... (system prompt) ...

Available Classes block (ephemeral cached)

# Available Ontology Classes

- Equipment (설비 / Equipment) [L2]
  LNG 생산기지 설비
- Process (공정 / Process) [L2]
  재기화 / 저장 / 송출
- OperatingEvent (운전 이벤트 / Operating Event) [L2]
  운전 이벤트 / 알람 이력

두 블록 모두 cache_control: {\"type\": \"ephemeral\"} — Class 카탈로그가 자주 안 변하므로 cache hit 률 70%+ 목표.

User message

Question: 재기화 공정 출구 압력 모니터링

Return up to 5 most relevant class names as JSON.

메트릭 (M3 Step 2 라벨 확장)

gend_ontology_mapper_suggestions_total{result} 의 result 추가 3종:

result	의미
`identifier_llm_success`	LLM 호출 성공 + 결과 받음
`identifier_llm_fail`	LLM 호출 실패 (retry exhausted / parse fail / unsafe stop_reason)
`identifier_substring_fallback`	LLM 실패 후 substring 으로 떨어짐 (실패 라벨과 함께 emit)

Grafana 패널 "Mapper result breakdown" 에서 자동 노출.

회귀 가드

파일	범위
`apps/api/tests/test_ontology_llm_identifier.py`	parse (stop_reason 분기 / JSON / 비-string filter / 빈 content) + format catalog + identify_llm (empty question / no key / invalid top_n / empty catalog / name→row 매핑 + cache_control 검증) + post_retry (429 → success / exhausts) + fallback (substring/llm/llm-failure/no-key) — 17
`apps/api/tests/test_ontology_instance_repo.py`	M3 Step 3 회귀 가드 정정 (offset 추가)

동작​

설정​

API​

identify_relevant_classes_with_fallback(db, question, *, top_n=5, method=\"llm\")​

identify_relevant_classes_llm(db, question, *, top_n=5, anthropic_key)​

Prompt 구성​

System message (ephemeral cached)​

Available Classes block (ephemeral cached)​

User message​

메트릭 (M3 Step 2 라벨 확장)​

회귀 가드​

관련​

동작

설정

API