Находите свойства схемы, которые могут задавать более одного вопроса: сравнивайте конкурирующие прочтения рядом и закрепляйте за каждым свойством единственное значение ещё до сбора данных.
Entity Enricher рассматривает LLM как базы знаний, к которым можно обращаться с запросами, а название свойства — это ваш вопрос. Когда название допускает несколько прочтений, каждая модель молча выбирает одно: так size у компании вернётся численностью сотрудников от одной модели, выручкой — от другой и площадью помещений — от третьей. Модели не разошлись в факте. Они ответили на разные вопросы, и теперь в вашей колонке смесь ответов, которую ни один потребитель данных не сможет различить.
Именно зафиксированный смысл делает обогащение сопоставимым между моделями и стабильным во времени. Он также упорядочивает всё, что идёт дальше: слияние нескольких моделей перестаёт видеть конфликты там, где на самом деле заданы два разных вопроса, а сравнения в бенчмарке перестают штрафовать модели за то, что они прочитали вашу схему иначе, чем эталон.
Факт, который просто меняется со временем, — это не неоднозначность. Схема — долговременный контракт, поэтому просто названное ceo означает «генеральный директор на момент обогащения», и повторный запуск схемы через год должен вернуть нового. Проверка никогда не предлагает зафиксировать дату в названии — это сломало бы все будущие запуски.
Вся проверка сводится к одному вопросу, задаваемому о каждом свойстве: если читать его имя в контексте родительского объекта, сколько разных вещей оно может запрашивать? Это число и есть вердикт.
| Прочтения | Вердикт | Что это значит |
|---|---|---|
| Ровно одно | Очистить | Все модели ищут одно и то же. Метки нет, исправлять нечего. |
| Два и более | Неоднозначно | Каждая модель останавливается на своём прочтении, поэтому в колонке незаметно смешиваются ответы на разные вопросы. Проверка называет конкурирующие прочтения и предлагает формулировку, оставляющую одно. |
| Нет | Невозможно сопоставить | Имя не называет ничего из того, что есть у родительского объекта, поэтому модель не может найти значение — она его выдумывает. Перечисленные прочтения анализатор рассмотрел и отклонил; помочь может только переименование или удаление: никакое описание не даст сущности свойство, которого у неё нет. |
Свойство, называющее ровно одну вещь, всё равно может быть отмечено, если не задана форма значения: читателю понятно, что спрашивают, но не в каких терминах придёт ответ. Вот типичные случаи:
| Частный случай | Пример | Что остаётся открытым |
|---|---|---|
| Неясный референт | Companysize | Имя указывает сразу на несколько разных фактов, которые действительно есть у родителя, — численность персонала, выручку, площадь помещений. Само имя не выбирает ни один из них. |
| Неясная величина или единица измерения | Companyannual_revenue | Факт один, но нет ни валюты, ни периода, ни указания «валовая/чистая» — правдоподобный ответ может ошибаться на три порядка и всё равно считаться «верным». |
| Неясная шкала или направление | Supplierrisk_score | Ни диапазон, ни направление шкалы не заданы: 0–10 или 0–100, и что означает высокое значение — выше безопасность или выше риск? Две модели могут дать противоположные результаты. |
| Нечёткий охват или границы | Companyemployees | Какое подмножество, какой уровень агрегации, чья точка зрения — вся группа или конкретная площадка, численность сотрудников или эквиваленты полной занятости, с подрядчиками или без. |
| Невозможно сопоставить | Authorrelease_year | У автора нет года выхода — он есть у его книг. Модель не может это найти и потому выдумывает. Переименуйте свойство в то, что принадлежит родительской сущности, или перенесите его в объект, у которого оно есть. |
Текстовые свойства — description, summary, notes, bio — никогда не помечаются. Их формулировки, конечно, различаются от модели к модели, но сам вопрос совершенно ясен, а проверка оценивает только это. Неоднозначность относится к вопросу, а не к тому, насколько похожи ответы.
Один лишь вердикт («это неясно») заставляет вас гадать, что имел в виду анализатор. Поэтому каждая находка несёт свои интерпретации: от двух до четырёх коротких различных прочтений, которые допускает свойство, начиная с наиболее вероятного. Этот список и есть находка: если анализатор не может назвать два прочтения, находка отбрасывается как шум и вам не показывается.
annual_revenue у сущности CompanyВместе с ними приходит предлагаемое описание, которое оставляет ровно одно прочтение — здесь: «суммарная выручка группы в USD за последний завершённый финансовый год, без вычета возвратов». Применить его ничего не стоит: описание попадает в модель обогащения точно так же, как и название, но свойство сохраняет своё имя, поэтому контракт данных не меняется. Когда вводит в заблуждение само название, находка также содержит предлагаемые названия.
Обычно достаточно увидеть прочтения выписанными, чтобы определиться со свойством быстрее любых объяснений: вы узнаёте то, которое имели в виду, а остальные — это то, что вы незаметно получали всё это время.
После генерации образца анализатор просматривает названия его свойств и возвращает отчёт о неоднозначности. Однозначные переименования применяются автоматически к ключам, придуманным ИИ (и никогда — к полям, названным вами), так что образец, который вы просматриваете, уже читается лучше. Анализатор также отмечает чрезмерно специализированные свойства — признаки, просочившиеся из примера экземпляра и подходящие только подтипу (медали спортсмена у обобщённой сущности Person), — и предлагает более узкий тип сущности. Проверка области идентичности выполняется здесь же отдельным вызовом, сразу после: она определяет форму связанных элементов до того, как вы просмотрите образец. Образцы, построенные на приложенных документах, пропускаются: их значения берутся из исходного документа, а не из памяти модели.
После сохранения сгенерированной схемы дополнительный проход аннотирует каждое свойство вердиктом о неоднозначности и предлагает переименования для тех, что остались спорными. Места связей к этому моменту уже аннотированы — генерация сама оценивает их область идентичности одним из своих шагов, — поэтому дополнительный проход охватывает только имена свойств. Этот шаг выполняется по мере возможности: если он не удастся, на саму генерацию это не повлияет.
Кнопка «Перепроверить» запускает обе проверки — имён свойств и мест связей — двумя параллельными вызовами. Это единственное место, где предлагается переписанное описание, а не переименование. Анализируется только то, что ещё не аннотировано; когда аннотировано всё, выполняется полный повторный анализ.
JSON-пример, который вы вставляете для создания схемы, можно проанализировать без сохранения состояния: вы получаете отчёт о неоднозначных и несопоставимых именах свойств, а также о связанных элементах, смешивающих факты о сущности с фактами о связке, — при этом ничего не изменяется.
Одна и та же находка в одном месте предлагает переименование, а в другом — описание, и причину стоит понимать. На этапе генерации описание ещё не существует самостоятельно: оно пишется по имени и потому может лишь повторить неоднозначность. Исправить можно только имя, и от него пока ничего не зависит. Поэтому и генерация примера, и дополнительный проход после генерации схемы предлагают переименования.
Когда схема уже используется, переименование свойства сдвигает столбцы, ломает запросы и меняет ключи синхронизированных таблиц, тогда как более точное описание доходит до модели столь же напрямую и больше ничего не затрагивает. Поэтому правило простое: пока от схемы ничего не зависит — переименовывайте; когда она уже используется — уточняйте описание, а переименование оставьте на случаи, когда проблема именно в имени.
Проверка носит исключительно рекомендательный характер. Ваши сохранённые схемы ничто не анализирует в фоне: она выполняется при генерации и когда вы нажимаете «Перепроверить». Она никогда не блокирует генерацию, не отклоняет обогащение, а её аннотации удаляются из каждого промпта, отправляемого моделям обогащения, — она информирует вас, а не ИИ.
Отмеченные свойства получают метку «ambiguous» в редакторе рабочих процессов: жёлтую, когда прочтения в основном совпадают и различаются лишь в краевых случаях, и красную, когда конкурирующие прочтения дадут существенно разные данные. У свойств, признанных однозначными, метки нет. При наведении на метку показываются заметка анализатора, найденные конкурирующие прочтения и предлагаемое описание или названия — решение и исправление в одной подсказке.
Вердикт выносится по названию и описанию свойства вместе, поэтому переименование свойства или изменение его описания сбрасывает аннотацию. Редактор помечает такие свойства как устаревшие и предлагает повторную проверку, которая анализирует только недостающее. Именно это и нужно после применения предложенного исправления: повторная проверка подтверждает, действительно ли новая формулировка закрепляет одно прочтение.
Разграничение идентичности — вторая проверка: она выполняется отдельным вызовом модели вместе с проходом по неоднозначности и попадает в тот же отчёт. Она рассматривает каждое место связи — элементы массива связанных объектов и вложенные объекты: если такое место смешивает факты о самой связанной сущности (её название, её страна) с фактами о паре (роль в отношении данного родителя, обозначение для конкретного родителя), у них оказывается одна идентичность — и повторные обогащения перезаписывают факты о паре у разных родителей. Такие места помечаются янтарным чипом «смешанные факты», во всплывающей подсказке которого показана рекомендуемая структура: собственные поля сущности вложены в подобъект, а поля пары остаются на элементе. Если элемент уже содержит такой подобъект, исправление проще — поля не на своём месте переносятся в уже существующий.
Разделение применяется во время генерации образца, до того как вы утвердите образец: структура фиксируется на первом образце, каждое перестроенное место связи перечисляется в предупреждениях генерации, а остальные образцы пакета генерируются по зафиксированной структуре. Поэтому схемы, сгенерированные из нового образца, обычно получаются чистыми. Образцы, основанные на прикреплённых документах, остаются такими, какими их задали источники, и вместо этого получают плашку.
Сама генерация схемы никогда не перестраивает утверждённый вами образец — она оценивает те же места и сообщает о найденном. Поэтому в существующей или написанной вручную схеме исправление живёт в плашке: она предлагает разделение в один клик, которое перестраивает образец и заново генерирует схему на его основе. Структура — это контракт, поэтому она меняется повторной генерацией из нового образца, а не правится на месте. Место связи, которое вы решили не разделять, продолжает работать — просто у него сохраняется одна общая идентичность и плашка. Плашка исчезает сама, когда набор полей элемента меняется.
Проверку можно отключить для отдельной схемы в меню дополнительных действий редактора рабочих процессов. При отключении пропускается проход после генерации, скрываются чипы, кнопка «Перепроверить» и предупреждения об устаревании, а конечные точки анализа возвращают ошибку ambiguity_check_disabled. Существующие аннотации сохраняются (просто скрываются), а если снова включить проверку для схемы, которая ещё ни разу не анализировалась, она запустится автоматически.
Любая сгенерированная схема изначально имеет включённую проверку, в том числе схемы, сгенерированные из приложенных документов. Неоднозначность — свойство формулировок схемы, а не источника значений одного запуска: документ определил эти значения один раз, а схема затем переиспользуется для сущностей, которых он никогда не охватывал. Документ меняет другое — шаг образца: имена его свойств взяты из словаря самого исходного документа, поэтому они никогда не переименовываются программно, и проверку несёт построенная на них схема.
«Годовая выручка компании» не добавляет ничего к тому, что уже несёт название, поэтому анализатор считает такое описание отсутствующим и оценивает одно лишь название. Описание оправдывает себя тогда, когда называет единицу измерения, период, масштаб или границу.
Заметки анализатора и интерпретации пишутся на языке вашего интерфейса: французский пользователь видит прочтения на французском, японский — на японском. Предлагаемые названия свойств остаются на английском — в соответствии с соглашениями об именовании в схемах.
Каждый анализ — это реальный (дешёвый) вызов модели; их два, выполняемых параллельно, когда нужно определить область и для мест связей. Каждый записывается как отдельный промпт у записи, с типом ambiguity_analysis, и списывается с кредитов, как и любое другое использование ИИ. Инкрементальные повторные проверки оплачиваются только за фактически проанализированные свойства и места связей.
Генерация примера и схемы сама по себе настроена так, чтобы каждое свойство называло ровно одну вещь, а описания указывали единицу измерения, шкалу и границу — а для спорных списков задавали верхний предел в описании, а не втискивали количество в имя. Поэтому большинство схем получаются чистыми, и анализатору остаётся выловить лишь отдельные случаи.
Проверка доступна программно:
| Поверхностное | Описание |
|---|---|
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 для аутентификации и полного каталога инструментов.