여러 질문을 동시에 던지고 있을 수 있는 스키마 속성을 찾아내고, 경합하는 해석을 나란히 비교하여 데이터를 수집하기 전에 각 속성의 의미를 하나로 고정하세요.
Entity Enricher는 LLM을 질의 가능한 지식 베이스로 다루며, 속성 이름은 곧 여러분이 던지는 질문입니다. 이름이 여러 해석을 허용하면 각 모델은 조용히 그중 하나를 고릅니다. 그래서 회사의 size가 어떤 모델에서는 직원 수로, 다른 모델에서는 매출액으로, 또 다른 모델에서는 바닥 면적으로 돌아옵니다. 모델들이 사실을 두고 의견이 갈린 것이 아닙니다. 서로 다른 질문에 답한 것이며, 그 결과 해당 열에는 후속 소비자가 구분할 수 없는 답들이 뒤섞여 담깁니다.
의미를 고정해야 보강 결과를 모델 간에 비교할 수 있고 시간이 지나도 안정적으로 유지됩니다. 이후 단계도 모두 정리됩니다. 다중 모델 융합은 실제로는 서로 다른 두 질문일 뿐인 충돌을 더 이상 충돌로 보지 않고, 벤치마크 비교도 기준과 다르게 스키마를 해석했다는 이유로 모델에 불이익을 주지 않습니다.
단순히 시간이 지나면서 바뀌는 사실은 모호성이 아닙니다. 스키마는 오래 유지되는 계약이므로, 그냥 ceo라고만 이름 붙인 속성은 “보강 시점의 CEO”를 뜻하며, 내년에 같은 스키마를 다시 실행하면 새 CEO가 반환되어야 합니다. 이 검사는 이름에 특정 날짜를 고정하도록 제안하지 않습니다. 그렇게 하면 이후의 모든 실행이 망가지기 때문입니다.
이 검사 전체는 모든 속성에 던지는 하나의 질문입니다. 상위 객체의 맥락에서 이름을 읽었을 때, 이 속성이 요구할 수 있는 별개의 것은 몇 가지인가? 그 개수가 곧 판정입니다.
| 해석 | 판정 | 무엇을 의미하나요 |
|---|---|---|
| 정확히 하나 | 지우기 | 모든 모델이 같은 것을 조회합니다. 칩도 없고 고칠 것도 없습니다. |
| 둘 이상 | 모호함 | 모델마다 제각기 다른 해석을 택하기 때문에, 해당 열에는 서로 다른 질문에 대한 답이 소리 없이 뒤섞입니다. 이 검사는 경합하는 해석들을 짚어 주고, 그중 하나만 남기는 문구를 제안합니다. |
| 없음 | 매핑 불가 | 이름이 상위 객체에 실제로 있는 것을 전혀 가리키지 않으므로, 모델은 값을 찾을 수 없어 지어냅니다. 나열된 해석들은 분석기가 검토했다가 기각한 것들이며, 해결책은 이름 변경 또는 삭제입니다. 어떤 설명도 엔터티에 없는 속성을 만들어 줄 수는 없습니다. |
정확히 한 가지만 가리키는 속성이라도 값의 기준이 정해져 있지 않으면 표시될 수 있습니다. 무엇을 묻는지는 알 수 있지만, 어떤 형태로 답이 돌아오는지는 알 수 없기 때문입니다. 자주 나타나는 유형은 다음과 같습니다:
| 하위 사례 | 예시 | 미확정 사항 |
|---|---|---|
| 지시 대상 불명확 | Companysize | 이름이 상위 객체가 실제로 가진 여러 별개의 사실 — 직원 수, 매출, 바닥 면적 — 을 동시에 가리킵니다. 이름만으로는 무엇인지 정해지지 않습니다. |
| 측정 대상 또는 단위 불명확 | Companyannual_revenue | 사실은 하나이지만 통화도, 기간도, 총액/순액 기준도 없습니다. 그럴듯한 답이 세 자릿수만큼 차이 나도 여전히 "정답"일 수 있습니다. |
| 척도 또는 방향 불명확 | Supplierrisk_score | 명시된 범위도 방향성도 없습니다. 0–10인가요, 0–100인가요? 높은 값이 더 안전하다는 뜻인가요, 더 위험하다는 뜻인가요? 두 모델이 서로 정반대로 해석할 수 있습니다. |
| 범위 또는 경계가 불명확함 | Companyemployees | 어떤 하위 집합인지, 어떤 집계 수준인지, 누구의 관점인지 — 그룹 전체인지 이 사업장인지, 인원수인지 상근 환산 인원인지, 계약직을 포함하는지 제외하는지. |
| 매핑 불가 | Authorrelease_year | 작가에게는 출간 연도가 없습니다. 출간 연도는 작가의 책에 있습니다. 모델은 이를 조회할 수 없으므로 지어냅니다. 상위 엔터티가 실제로 가진 것으로 이름을 바꾸거나, 그 값을 가진 객체로 옮기세요. |
산문형 속성 — description, summary, notes, bio — 은 절대 표시되지 않습니다. 표현은 당연히 모델마다 다르지만 묻는 질문 자체는 완벽하게 명확하며, 이 검사가 판단하는 것은 그것뿐입니다. 모호성은 질문에 관한 것이지, 답이 서로 얼마나 비슷해 보이는지에 관한 것이 아닙니다.
판정만 덩그러니 주어지면(“이건 불분명합니다”) 분석기가 무엇을 염두에 두었는지 짐작해야 합니다. 그래서 모든 발견 항목에는 해석이 함께 제공됩니다. 해당 속성이 허용하는 서로 다른 짧은 해석을 두 개에서 네 개까지, 가능성이 높은 순서로 보여 줍니다. 이 목록이 곧 발견 항목입니다. 분석기가 두 가지 해석을 제시하지 못하면 그 항목은 노이즈로 간주되어 표시되지 않습니다.
annual_revenue Company 객체에서그와 함께 해석을 정확히 하나만 남기는 설명 제안이 제시됩니다. 여기서는 “가장 최근에 종료된 회계연도의 그룹 총매출(USD, 반품 차감 전)”입니다. 이를 적용해도 잃는 것은 없습니다. 설명은 이름과 똑같이 보강을 수행하는 모델에 전달되지만 속성 이름은 그대로 유지되므로 데이터 계약은 바뀌지 않습니다. 이름 자체가 오해를 부르는 경우에는 발견 항목에 이름 제안도 함께 포함됩니다.
해석들을 하나씩 펼쳐 놓고 보면 어떤 설명보다도 빠르게 속성이 정리됩니다. 의도했던 해석을 바로 알아보게 되고, 나머지는 그동안 모르는 사이에 받아 온 값들입니다.
샘플이 생성되면 분석기가 속성 이름을 검토하여 모호성 보고서를 반환합니다. 명백한 이름 변경은 AI가 만들어 낸 키에 자동으로 적용되므로(직접 이름을 지정한 필드에는 절대 적용되지 않습니다), 검토하는 샘플은 이미 더 읽기 좋은 상태가 됩니다. 또한 지나치게 특수화된 속성, 즉 예시 인스턴스에서 흘러 들어와 하위 유형에만 들어맞는 특성(일반적인 Person에 붙은 운동선수의 메달 등)도 표시하고, 더 좁은 엔터티 유형을 제안합니다. 아이덴티티 범위 지정 검사는 바로 이어서 별도의 호출로 실행되어, 샘플을 검토하기 전에 관련 항목의 형태를 확정합니다. 첨부된 문서에 근거한 샘플은 건너뜁니다. 그 값은 모델의 기억이 아니라 원본 문서에서 나오기 때문입니다.
생성된 스키마가 저장되면 후처리 단계가 모든 속성에 모호성 판정을 주석으로 달고, 여전히 모호한 속성에는 이름 변경을 제안합니다. 관계 지점은 그 시점에 이미 주석이 달려 있으므로 — 생성 과정이 자체 단계 중 하나로 범위 지정을 직접 판단합니다 — 후처리는 속성 이름만 다룹니다. 이 단계는 최선 노력 방식이며, 실패하더라도 생성 자체에는 영향이 없습니다.
재검사 버튼은 속성 이름과 관계 지점, 두 가지 검사를 병렬 호출 두 개로 실행합니다. 이름 변경 대신 다시 작성한 설명을 제안하는 유일한 곳입니다. 아직 주석이 없는 항목만 분석하며, 모든 항목에 주석이 달리면 전체 재분석으로 전환합니다.
스키마 생성을 위해 붙여 넣은 샘플 JSON은 상태를 저장하지 않고 분석할 수 있습니다. 아무것도 수정하지 않은 채, 모호하거나 매핑할 수 없는 속성 이름과 엔터티 사실에 페어링 사실을 섞은 관련 항목에 대한 보고서를 받게 됩니다.
같은 발견 사항이 어떤 곳에서는 이름 변경을, 다른 곳에서는 설명을 제안하는데, 그 이유는 알아 둘 만합니다. 생성 시점에는 설명이 아직 독립적으로 존재하지 않습니다. 이름으로부터 작성되므로 모호성을 되풀이할 수밖에 없습니다. 고칠 수 있는 것은 이름뿐이고, 아직 이름에 의존하는 것도 없습니다. 그래서 샘플 생성과 스키마 생성 후처리 단계 모두 이름 변경을 제안합니다.
스키마가 운영에 들어간 뒤에 속성 이름을 바꾸면 컬럼이 이동하고 쿼리가 깨지며 동기화된 테이블의 키가 다시 지정됩니다. 반면 더 명확한 설명은 모델에 똑같이 직접 전달되면서 다른 것은 아무것도 바꾸지 않습니다. 그래서 규칙은 간단합니다. 스키마에 의존하는 것이 생기기 전에는 이름을 바꾸고, 운영에 들어간 뒤에는 설명으로 의미를 고정하세요. 그리고 이름 자체가 문제인 경우를 위해 이름 변경은 아껴 두세요.
이 검사는 참고용일 뿐입니다. 저장된 스키마를 백그라운드에서 분석하는 일은 없습니다. 생성 시점과 재검사를 누를 때만 실행됩니다. 생성을 막지 않고 보강을 거부하지도 않으며, 주석은 보강 모델로 보내는 모든 프롬프트에서 제거됩니다. AI가 아니라 사용자에게 알리기 위한 기능입니다.
표시된 속성은 워크플로 편집기에서 “ambiguous” 칩을 함께 보여 줍니다. 해석이 대부분 겹치고 예외적인 경우에서만 갈릴 때는 주황색, 경합하는 해석이 실질적으로 다른 데이터를 낳을 때는 빨간색입니다. 명확하다고 판정된 속성에는 칩이 붙지 않습니다. 칩 위에 마우스를 올리면 분석기의 메모, 찾아낸 경합 해석, 제안된 설명이나 이름이 표시되므로 판단 근거와 수정 방법을 같은 툴팁에서 확인할 수 있습니다.
판정은 속성의 이름과 설명을 함께 보고 내려집니다. 따라서 속성의 이름을 바꾸거나 설명을 수정하면 기존 판정이 사라집니다. 편집기는 이런 속성을 오래된 상태로 강조 표시하고, 누락된 부분만 분석하는 재검사를 제안합니다. 제안된 수정을 적용한 뒤에 필요한 것이 바로 이 재검사입니다. 새 문구가 정말로 하나의 해석만 남기는지 확인해 주기 때문입니다.
아이덴티티 범위 검사는 두 번째 검사로, 모호성 검사와 함께 별도의 모델 호출로 실행되어 같이 보고됩니다. 관련 배열의 항목과 중첩 객체 등 모든 관계 지점을 검토합니다. 어떤 항목이 관련 엔티티 자체에 관한 정보(이름, 국가)와 연결 관계에 관한 정보(이 상위 항목에서 맡은 역할, 상위 항목별 지정값)를 함께 담고 있으면 둘이 하나의 아이덴티티를 공유하게 되고, 다시 보강할 때 여러 상위 항목에 걸쳐 연결 관계 정보가 덮어써집니다. 이러한 지점에는 황색 “정보 혼재” 칩이 표시되며, 툴팁에서 권장 구조를 보여 줍니다. 엔티티 고유 필드는 하위 객체로 중첩하고, 연결 관계 필드는 항목에 그대로 두는 방식입니다. 항목에 이미 그런 하위 객체가 있다면 수정은 더 간단합니다. 잘못 놓인 필드를 이미 있는 객체로 옮기기만 하면 됩니다.
분할은 샘플을 승인하기 전 샘플 생성 단계에서 적용됩니다. 첫 번째 샘플에서 형태가 확정되고, 재구성된 모든 지점이 생성 경고에 나열되며, 배치의 나머지 샘플은 확정된 형태에 맞춰 생성됩니다. 따라서 새 샘플로 생성한 스키마는 보통 문제없이 나옵니다. 첨부된 문서에 근거한 샘플은 원본이 의도한 형태 그대로 두고, 대신 칩이 표시됩니다.
스키마 생성 자체는 승인한 샘플을 재구성하지 않습니다. 동일한 지점을 판단해 발견한 내용을 보고할 뿐입니다. 따라서 기존 스키마나 직접 작성한 스키마에서는 칩이 곧 수정 수단입니다. 칩은 원클릭 분할을 제공하여 샘플을 재구성하고 그로부터 스키마를 다시 생성합니다. 구조가 곧 계약이므로, 새 샘플로부터 다시 생성하는 방식으로 변경될 뿐 그 자리에서 수정되지는 않습니다. 분할하지 않기로 한 지점도 계속 작동합니다. 다만 하나의 아이덴티티를 공유한 채 칩이 남아 있을 뿐입니다. 항목의 필드 구성이 바뀌면 칩은 저절로 사라집니다.
이 검사는 워크플로 에디터의 더보기 메뉴에서 스키마별로 끌 수 있습니다. 비활성화하면 생성 후 처리 단계를 건너뛰고, 칩과 재검사 버튼, 오래됨 경고가 숨겨지며, 분석 엔드포인트는 ambiguity_check_disabled 오류를 반환합니다. 기존 주석은 (숨겨질 뿐) 유지되며, 한 번도 분석된 적 없는 스키마에서 검사를 다시 켜면 자동으로 실행됩니다.
생성된 모든 스키마는 검사가 켜진 상태로 시작하며, 첨부 문서에서 생성된 스키마도 마찬가지입니다. 모호성은 스키마가 어떻게 표현되었는지에 관한 속성이지, 특정 실행의 값이 어디에서 왔는지에 관한 것이 아닙니다. 문서는 그 값을 한 번 확정했을 뿐이고, 스키마는 그 문서가 다루지 않은 엔티티에도 계속 재사용됩니다. 문서가 실제로 바꾸는 것은 샘플 단계입니다. 샘플의 속성 이름은 원본 문서 자체의 어휘에서 나오므로 코드에서 이름이 변경되지 않으며, 대신 그 이름으로 만들어진 스키마에 검사가 적용됩니다.
“회사의 연간 매출”은 이름이 이미 담고 있던 정보에 아무것도 더하지 않으므로, 분석기는 이런 설명을 없는 것으로 간주하고 이름만으로 판단합니다. 설명은 단위, 기간, 규모 또는 범위를 명시할 때 비로소 제 역할을 합니다.
분석기의 메모와 해석은 사용자의 인터페이스 언어로 작성됩니다. 프랑스어 사용자에게는 프랑스어 해석이, 일본어 사용자에게는 일본어 해석이 표시됩니다. 제안되는 속성 이름은 스키마 이름 규칙에 맞춰 영어로 유지됩니다.
각 분석은 실제 모델 호출이며(비용은 저렴합니다), 범위를 정해야 할 관계 지점이 함께 있으면 두 번의 호출이 병렬로 실행됩니다. 각 호출은 레코드에 ambiguity_analysis 유형의 개별 프롬프트로 기록되고, 다른 AI 사용량과 마찬가지로 크레딧에서 차감됩니다. 증분 재검사에서는 실제로 분석한 속성과 지점에 대해서만 비용이 발생합니다.
샘플 생성과 스키마 생성 자체가 속성 하나당 한 가지만 지칭하도록, 그리고 단위·척도·경계를 명시한 설명을 작성하도록 지시받습니다. 논쟁의 여지가 있는 목록에는 개수를 이름에 억지로 넣는 대신 설명에 상한을 적습니다. 그래서 대부분의 스키마는 깔끔하게 나오고, 분석기는 남은 소수만 잡아내면 됩니다.
이 검사는 프로그래밍 방식으로도 사용할 수 있습니다:
| 표면 형식 | 설명 |
|---|---|
POST /api/schema/analyze-sample | 붙여넣은 샘플 JSON을 분석합니다 — 한 번의 요청으로 두 검사를 병렬 실행하며, 상태를 저장하지 않는 보고서로 아무것도 변경되지 않습니다 |
POST /api/schema/saved/{id}/analyze | 저장된 스키마를 분석하고 두 검사의 주석을 기록합니다 — 기본값은 증분 방식이며, force=true는 전체를 다시 분석합니다 |
POST /api/schema/scoping-split | 샘플 세트에 "혼합된 사실" 분할을 한 번 적용합니다 — 결정적이고 무료이며 아무것도 저장되지 않습니다. 반환된 샘플을 스키마 생성에 다시 사용하세요 |
analyze_sample | MCP 도구 — Claude 또는 모든 MCP 클라이언트에서 실행하는 동일한 상태 비저장 샘플 보고서, 두 검사 모두 포함 |
analyze_schema | MCP 도구 — 저장된 스키마에 주석을 추가합니다. update_schema와 함께 사용하면 제안된 설명이나 이름 변경을 적용할 수 있습니다 |
발견 항목에는 kind(ambiguous 또는 unmappable), level, 메모, interpretations 목록, 그리고 제안된 수정 사항이 포함됩니다. 저장된 스키마에서는 각 속성에 ambiguity로 저장되며, 샘플 생성 시에는 ambiguity_report 아래에 반환됩니다.
인증과 전체 도구 카탈로그는 API 레퍼런스와 MCP Server 가이드를 참조하세요.