시맨틱 ID

같은 종류의 엔터티를 반복해서 보강하다 보면, 같은 회사, 같은 약물 부작용, 같은 사람처럼 동일한 현실 세계의 대상을 매번 조금씩 다른 표현으로 계속 다시 발견하게 됩니다. 시맨틱 ID는 Entity Enricher가 객체의 핵심 필드로부터 부여하는 안정적인 조직 범위 식별자로, 이러한 유사 중복 항목이 그룹화, 중복 제거, 조인이 가능한 하나의 정체성으로 통합됩니다.

문제: 같은 것, 다른 표현

객체의 정체성은 키 필드로 구성되며, 하나 또는 여러 개일 수 있습니다. 두 가지 예시:

키 하나

`name`을 키로 하는 부수 효과입니다

실행과 언어에 따라 Headache, Céphalée, Cephalalgia로 나타납니다. 하나의 키 필드, 세 가지 표기, 하나의 실제 개념입니다.

키 두 개

`이름` + `국가`로 키가 지정된 회사

Acme Inc. · United States와 Acme Incorporated · United States는 같은 회사이지만, Acme Inc. · Germany는 다른 회사입니다. 두 번째 키가 이를 구분해 주며, 그래서 하나의 객체가 여러 키를 가질 수 있습니다.

단순 문자열 매칭은 이 모든 경우에 실패하지만, 사람은 어느 것이 동일한지 압니다. 시맨틱 ID는 그러한 판단을 자동으로 인코딩합니다.

시맨틱 ID란

•객체의 단일 string 속성(기본 이름은 id)으로, 불투명하고 안정적인 식별자를 담습니다.
•안정적이며 organization 범위로 한정 — 동일한 실제 대상은 오직 해당 organization 내에서 enrichment, batch, 시간에 관계없이 동일한 ID로 해석됩니다.
•자동으로 할당되며, 절대 LLM이 할당하지 않습니다 — 강화 후 처리 단계에서 계산되므로 모델이 이를 환각으로 만들어낼 수 없습니다. 이 필드는 통과(pass-through) 필드입니다(입력 값이 그대로 전달됩니다). 항상 문자열이며, 키가 아니고, preserve가 아니며, 다국어가 아니고, 객체당 최대 하나입니다.
•모든 객체에서 허용됩니다 — 전체 엔터티(루트), 1-1 중첩 객체(예: manufacturer), 또는 배열의 각 항목(예: 각 side_effect).

작동 방식

모델이 결과를 반환하면 Entity Enricher는 각 시맨틱 ID를 여섯 단계에 걸쳐, 비용이 낮은 순서대로 해석합니다. 임베딩 이전의 네 단계는 순수한 텍스트 비교이므로, 그 단계에서 확정된 아이덴티티는 비용이 전혀 들지 않습니다:

신원 텍스트를 작성하세요

객체의 키 필드를 기본 언어로 하나의 문자열로 결합합니다. 중첩된 엔티티의 키도 모호성 해소를 위해 함께 사용됩니다. 다른 영화와 제목이 같은 영화는 감독 이름으로 구분되는 식입니다. 반대로 같은 관련 엔티티를 참조하는 모든 형제 항목은 동일한 값을 갖게 되므로, 관련 키가 형제 항목을 서로 비슷하게 보이게만 만든다면 구성 요소에서 제거하세요. 배열 안의 항목은 절대 포함되지 않습니다. 각 배열 항목은 자체 아이덴티티를 갖습니다. 스키마 편집기의 아이덴티티 구성 요소 목록에는 어떤 값이 텍스트를 구성하는지 정확히 표시되며 순서를 바꾸거나 변경할 수 있습니다 — 동일한 구성 요소를 동일한 순서로 선택한 스키마는 동일한 ID를 생성합니다. 텍스트는 사소한 차이를 줄이기 위해 정규화됩니다(소문자화, 괄호 내용 제거, 공백 축약). 이 키 필드가 모두 비어 있으면 객체를 식별할 근거가 없어 ID를 부여할 수 없습니다. 그래서 그룹화도, 조인도, 중복 제거도 할 수 없는 익명 객체로 남기는 대신 객체를 제거합니다. 중첩된 객체는 상위 객체에서 null이 되고, 목록 안의 항목은 목록에서 삭제됩니다. 인리치먼트된 엔티티 자체는 절대 제거되지 않으며, 단지 ID가 없을 뿐입니다.

정확히 일치하는 항목을 찾습니다

정규화된 해당 텍스트가 조직에서 이전에 확인된 적이 있으면 기존 ID가 즉시 재사용됩니다. 모델 호출도, 비용도 없습니다.

코드가 있다면 코드로 매칭합니다

객체 자체의 아이덴티티 키 중 하나가 코드인 경우 — 패턴이 지정된 필드이거나 예시가 식별자처럼 보이는 필드 — 그 값이 가장 먼저 구성되어 단독으로 비교됩니다(관련 엔티티의 코드는 대신 사용되지 않습니다. 그 엔티티를 참조하는 모든 형제 항목이 같은 코드를 공유하기 때문입니다). 코드가 정확히 일치하면 주변 표현과 관계없이 아이덴티티가 즉시 결정되므로, LC-39A는 나머지 텍스트가 어떻게 작성되었든 모두 하나로 묶습니다. 그에 못지않게 중요한 것은 반대 방향으로도 작동한다는 점입니다. 코드가 다르면 임베딩 단계에서는 병합했을 항목이라도 병합이 거부됩니다. 식별자가 다른 두 대상은 아무리 비슷해 보여도 서로 다른 대상이기 때문입니다.

순서와 관계없이 동일한 단어로 매칭합니다

임베딩 비용을 쓰기 전에 단어 자체를 집합으로 비교합니다. 한 텍스트의 단어가 다른 텍스트의 단어에 모두 포함된다면, 두 텍스트는 길이만 다를 뿐 같은 아이덴티티입니다 — “Boeing”과 “The Boeing Company”처럼 말입니다. 이 방식은 임베딩이 서로 멀다고 판정하는 바로 그 표현 길이 차이를 잡아내며, 비용도 전혀 들지 않습니다. 정확한 텍스트 비교 단계와 마찬가지로, 여기서 일치하면 임베딩 호출도 과금도 없습니다.

임베드 및 비교

그렇지 않으면 텍스트가 임베딩되어, 벡터 유사도를 사용해 동일한 개념 유형(기본값은 엔터티 유형 이름 — 편집기에서 재정의할 수 있어 이름이 다른 스키마도 하나의 개념 공간을 공유합니다)의 기존 개념과 의미 기준으로 비교됩니다 — 그래서 “Acme Inc.”와“Acme Incorporated”가 서로 가까이 놓입니다.

판정 모델에 묻기

가장 가까운 개념 몇 개가 소형 언어 모델에 전달되고, 모델은 한 가지 질문에 답합니다. 그중 현실의 동일한 대상을 가리키는 것이 있는가? 모델은 각 명칭을 레이블이 붙은 부분들로 볼 뿐, 유사도 점수는 절대 보지 않습니다. 점수를 보면 기하학적 수치를 믿게 될 뿐이기 때문입니다. 그렇다고 답하면 해당 ID가 재사용되고 새 표현은 같은 개념의 또 다른 표기로 기억되므로, 다음에 등장할 때는 비용이 들지 않습니다. 아니라고 하거나 판단할 수 없다고 하면 완전히 새로운 ID가 생성됩니다. 그 반대는 결코 일어나지 않는데, 두 행을 나중에 병합하기는 쉬워도 잘못 융합된 한 행은 그렇지 않기 때문입니다.

숫자가 아니라 모델을 쓰는 이유: 유사도만으로는 양쪽 방향 모두에서 틀립니다. 같은 조선소를 가리키는 두 표기가 아주 다른 점수를 받을 수 있는 반면, 어떤 상태와 그 반대(“급성” 대 “만성”)는 거의 동일한 점수를 받습니다. 어떤 임계값도 이 둘을 갈라내지 못하며, 오직 단어의 의미에 대한 지식만이 그렇게 할 수 있습니다. 판정 하한(기본값 0.5, 속성별로 조정 가능)은 물어볼 가치가 있는 후보를 어디까지 찾을지만 정할 뿐, 동일성을 결정하지는 않습니다.

입력 ID 대 생성된 ID

ID가 생성되는지는 해당 객체의 입력에 이미 존재하는지에 따라 달라집니다. 이것이 왕복(round-trip)을 가능하게 합니다: 한 번 보강하여 ID를 얻은 다음, 이후 실행에서 알려진 ID를 다시 전달하여 동일한 정체성에 새로운 정보를 붙일 수 있습니다 — 더 저렴하고 모호하지 않습니다.

입력에 이미 있는 ID → 유지됨(조회)

전송하는 객체에 이미 시맨틱 ID가 있으면 조회로 처리됩니다. ID는 그대로 유지되고, 레코드는 기존 개념에 연결되며, 임베딩이 없습니다 — 비용도, 일치 또는 생성도 없습니다. 플랫폼에 "이 객체는 이미 우리 데이터베이스에서 식별되었습니다"라고 알려주는 것입니다.

입력에 ID가 없음 → 생성됨

객체에 시맨틱 ID가 없으면 플랫폼이 위 단계에 따라 생성합니다. 이후 그 ID는 조직 데이터베이스에서 해당 객체의 고정 식별자가 됩니다.

존재하지만 인식할 수 없는 값(실제 개념 ID가 아닌 값)은 무시되며, 대신 ID가 생성됩니다.

활성화하는 방법

임베딩 모델을 선택하세요 (조직당 한 번)

소유자는 Settings → Organization → Defaults에서 임베딩이 가능한 모델을 조직의 기본 임베딩 모델로 선택합니다(플랜에 따라 제한되는 설정입니다. 어떤 모델이 임베딩을 지원하는지는 Models & Pricing을 참고하세요). 저장된 벡터는 모델 간에 비교할 수 없으므로, 개념이 하나라도 존재하면 이 설정은 해제만 가능합니다 — 모델 변경은 Semantic IDs 페이지에서 마이그레이션으로 실행되며, 모든 개념을 다시 임베딩하되 ID는 그대로 유지합니다. 모델이 없으면 시맨틱 ID는 그대로 건너뜁니다.

스키마에 시맨틱 ID 추가

두 가지 방법이 있으며, 모두 Workflow Editor에 있습니다:

생성 시 자동으로 — “유형에 대한 시맨틱 ID 생성”을 체크하세요. 키가 있는 모든 객체(자체 키 또는 1-1 중첩 객체의 키)는 루트 엔터티를 포함해 하나씩 부여받습니다.
수동으로 — 아무 객체나 엔티티 하단에 있는 “+ 시맨틱 ID 추가” 컨트롤을 사용합니다.

해석은 강화당 소량의 임베딩 사용량이 듭니다(다른 모델 호출과 마찬가지로 측정됨). 정확히 일치하는 캐시는 반복 시 무료이며, 입력으로 제공된 ID는 비용이 들지 않습니다.