Как скрыть служебные метаданные документа от LLM в LlamaIndex

1. Разделите метаданные на публичные поля, служебные идентификаторы и секреты; последние вообще не помещайте в Document.
2. Создайте тестовый Document с file_name и category, укажите excluded_llm_metadata_keys для file_name.
3. Напечатайте get_content с MetadataMode.LLM и проверьте отсутствие file_name при сохранении фактического текста.
4. Отдельно решите, должен ли file_name влиять на embedding; при необходимости исключите и там.
5. Повторите тест на node после индексации и проверьте, что UI не выдаёт скрытый путь как ссылку.

Готовый шаблон Python

from llama_index.core import Document
from llama_index.core.schema import MetadataMode

doc = Document(text="Правило возврата: 14 дней.",
               metadata={"file_name": "internal-r7.txt", "category": "returns"})
doc.excluded_llm_metadata_keys = ["file_name"]
llm_text = doc.get_content(metadata_mode=MetadataMode.LLM)
embed_text = doc.get_content(metadata_mode=MetadataMode.EMBED)
assert "internal-r7.txt" not in llm_text
print(llm_text, embed_text)

Код ниже в статье предназначен для тестовых источников без персональных сведений. Вызовы SDK не выполнялись в данном окружении с реальной моделью; синтаксис Python проверен отдельно. Не переносите вывод демонстрационного эксперимента на любой корпус и любого провайдера без повторной проверки.

Пример входа и ожидаемого результата

Вход: Document с текстом о сроке 14 дней и служебным file_name=internal-r7.txt. Ожидается, что LLM-представление не содержит file_name, а embedding-представление может его содержать, пока вы не добавили excluded_embed_metadata_keys. Это проверка подготовки контекста, не доказательство безопасности всей системы хранения.

Сохраните входные файлы, идентификаторы документов и ожидаемое утверждение в отдельном проверочном наборе. При неуспехе выделяйте слой ошибки: чтение источника, преобразование в nodes, получение embedding, поиск, синтез ответа или UI. Правильная форма ответа ещё не гарантирует правильного происхождения сведений.

Диагностика и границы решения

Исключение метаданных из промпта нельзя использовать как способ хранения секретов. API-ключ, личный адрес или токен, включённые в Document, остаются в объекте и могут попасть в логи, storage или ответы другого компонента. Для таких данных требуется удаление до создания документа и отдельный контроль доступа. Служебный file_name может помогать в поиске, но путь на сервере почти никогда не следует показывать как URL пользователю. Сравнивайте LLM- и EMBED-представления до вызова внешней модели: без этого можно неожиданно передать ей внутреннее название файла. Исключение file_name из embeddings изменяет векторное представление, поэтому после изменения параметров переиндексируйте данные и измерьте retrieval. Если категория используется для фильтрации, её исключение из текста embeddings не обязательно удаляет поле metadata для структурного фильтра; тестируйте оба механизма отдельно.

Дополнительный проверочный сценарий

Создайте файл с нейтральным текстом и служебным названием, содержащее слово «секретный»; спросите, попадает ли это слово в LLM-представление. Затем добавьте клиентский tenant ID в metadata и убедитесь, что фильтр доступа не зависит от того, видит ли ID генератор. Обратите внимание на узлы после разбиения: поля наследуются, поэтому настройка исключений должна быть проверена на том уровне, который реально передаётся в prompt. Если metadata выводится в citations или трассировке, тест одной лишь строки MetadataMode.LLM не гарантирует отсутствия утечки. Сформируйте матрицу каналов: промпт, embeddings, storage, UI, логи и экспорт. Для каждого пометьте допустимые поля и проверьте отдельно.

Критерии проверки