시맨틱 ID - Entity Enricher 문서

시맨틱 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”가 서로 가까이 놓입니다.

재사용 또는 새로 발급

가장 가까운 항목의 점수가 유사도 임계값(기본값 0.92, 속성별 조정 가능)을 넘으면 해당 개념의 ID가 재사용됩니다. 그렇지 않으면 완전히 새로운 ID가 생성되어 다음을 위해 저장됩니다. 점수가 높아도 예외가 하나 있습니다. 두 텍스트가 같은 단어로 이루어져 있고 세는 수만 다른 경우 — “두 번째 단계”와“세 번째 단계” — 서로 다른 것으로 처리됩니다. 숫자를 세는 것이 바로 둘을 구분하는 기준이기 때문입니다. 같은 숫자를 다르게 표기한 경우(2와II)는 여전히 일치합니다.

임계값 트레이드오프: 임계값이 높을수록 더 엄격하고(우발적 병합 감소), 낮을수록 더 느슨합니다(더 공격적인 중복 제거). 기본값 0.92가 과도하게 병합하거나 부족하게 병합할 때 property별로 조정하세요.

입력 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는 비용이 들지 않습니다.