Как да изградите неутрална за доставчика LLM наблюдаемост с OpenTelemetry

Наблюдаемостта на LLM се нарушава, когато всеки екип на приложението регистрира отговорите на доставчика в свой собствен формат. По време на инцидент екипите на платформата трябва да отговорят на конкретни въпроси: кой екип е направил заявката, кой API ключов обхват е бил използван, кой модел е бил заявен, кой доставчик действително го е обслужвал, дали е настъпил повторен опит или резервен опит, колко токена са били изразходвани, кое време на забавяне е променено и кой клас на грешка е причинил неуспеха. Те също се нуждаят от тези отговори, без да копират необработени подкани, завършвания, ключове на доставчик или идентификатори на клиенти в общи хранилища на регистрационни файлове.

Практическият отговор е да се използва многомоделният API шлюз като контролна точка за наблюдение. Проследяването на ниво приложение все още има значение, но шлюзът е мястото, където изборът на доставчик, повторните опити, резервните варианти, отчитането на използването, собствеността върху заявките и прилагането на поверителността могат да бъдат нормализирани, преди телеметрията да достигне до инструментите надолу по веригата. За екипи, управляващи корпоративен LLM API, това се превръща в разликата между разпръснати данни за отстраняване на грешки и неутрален по отношение на доставчика оперативен модел.

Дефинирайте първо договора за наблюдение

Започнете с писмен договор за атрибути, а не екранни снимки на таблото за управление. Договорът трябва да дефинира минималните метаданни, които всяка заявка за LLM трябва да излъчва, на кои полета е разрешено да напускат шлюза, кои полета са ограничени и кои полета никога не се експортират.

Полезният основен договор включва метаданни за собственост, маршрутизиране, модел, използване, латентност и резултат. Атрибутите на собственост идентифицират организацията, екипа, средата, работното натоварване, приложението и API обхвата на ключа. Атрибутите за маршрутизиране идентифицират маршрута на шлюза, версията на правилата, заявения доставчик, заявения модел, избрания доставчик, избрания модел, броя повторни опити, резервния брой и дали е използван стрийминг. Атрибутите за използване улавят входни токени, изходни токени, кеширани входни токени, логически токени, когато са налични, брой заявки и прогнозен клас на разходите. Атрибутите на резултата улавят статус, код на грешка на доставчика, когато е безопасно, нормализиран клас на грешка, резултат от валидиране, състояние на изчакване и модел на окончателен отговор.

Поддържайте неутрален доставчик на договора. Специфична за доставчика грешка, като отговор на ограничение на скоростта, отговор на претоварен модел, неуспешно валидиране на схема, отказ за безопасност, изчакване или грешка в контекстния прозорец, трябва да съответства на нормализиран клас на грешка, който таблата за управление могат да групират между доставчици. Оригиналният код за грешка на доставчика може да е полезен, но трябва да се третира като ограничени диагностични данни, а не като основно измерение на таблото за управление.

Използвайте модел на обхват, центриран върху шлюз

Ясната структура на проследяване предотвратява превръщането на телеметрията на LLM в плоска купчина участъци. Използвайте един интервал на заявка за входящо приложение, един диапазон на логическа LLM операция и дъщерни интервали за работата, която шлюзът изпълнява.

Типичната йерархия изглежда така:

inbound.http_request
  llm.operation
    llm.provider_attempt
    llm.provider_attempt.retry
    llm.provider_attempt.fallback
    retrieval.query
    tool.call
    output.validation

Обхватът на входящите заявки представлява заявката на повикващия към шлюза. Обхватът на логическата LLM операция представлява видимата за потребителя LLM задача, дори ако шлюзът прави множество опити за доставчик. Обхватът на опитите на доставчика обхваща всяко действително повикване към модел нагоре по веригата API. Обхватите за извличане, инструмент и валидиране трябва да бъдат дъщерни на логическата операция, когато са част от изготвянето на крайния отговор.

Това разделяне има значение по време на инциденти. Ако заявка се върне от един модел към друг, логическата операция може да успее, докато първият опит за доставчик е неуспешен. Ако крайният резултат не успее при проверката на схемата, опитът за доставчик може да е технически успешен, докато логическата операция е неуспешна. Без отделни интервали, таблата за управление или скриват грешките на доставчика зад успешни отговори на крайния потребител, или преувеличават грешките, които са били успешно възстановени.

Картиране на OpenTelemetry GenAI атрибути зад вътрешен Mapper

Съществуват семантични конвенции на OpenTelemetry, така че производителите на телеметрия използват общи имена и атрибути в кодови бази, библиотеки и платформи.Проектът OpenTelemetry сега насочва Generative AI конвенции към отделно хранилище на GenAI и тези конвенции дефинират атрибути на искане и отговор на модела, като име на доставчик, заявен модел, модел на отговор, входни токени, изходни токени, логически токени и кеширани входни токени.

Използвайте тези GenAI атрибути, където са подходящи, но не разпръсквайте необработени имена на атрибути в кода на шлюза. Увийте ги зад малък телеметричен картограф. Този картограф трябва да приеме вътрешен запис на заявка и да създаде стандартизирани атрибути за обхват.

record LlmTelemetryContext {
  organization_id
  team_id
  environment
  api_key_scope
  route_name
  route_policy_version
  workload_class
  provider_requested
  model_requested
  provider_selected
  model_response
  input_tokens
  output_tokens
  cached_input_tokens
  reasoning_tokens
  retry_count
  fallback_count
  normalized_error_class
}

Картографът може да излъчва атрибути на OpenTelemetry GenAI за стандартните полета и частни атрибути на шлюза за бизнес контекст. Съхранявайте частни атрибути под контролирано пространство от имена, например llm_gateway.organization_id, llm_gateway.team_id, llm_gateway.key_scope, llm_gateway.route_policy и llm_gateway.workload_class.

Този дизайн ви дава неутрална спрямо доставчика телеметрия, като същевременно защитава кодовата база от изтичане. Конвенциите на GenAI все още се развиват, така че картографът е мястото, където имената могат да се променят, без да се редактират всеки манипулатор, модул за повторен опит, адаптер за поточно предаване и компонент за валидиране.

Разделете метаданните от чувствителното съдържание

LLM следите са необичайно чувствителни, тъй като най-полезните данни за отстраняване на грешки може да са същите данни, които не трябва да се съхраняват широко: подкани, извлечени документи, инструмент параметри, завършвания, потребителски идентификатори, клиентски идентификатори и необработени идентификационни данни на доставчик. Позицията по подразбиране трябва да е видимост на първо място за метаданни.

Препоръчителните полета по подразбиране включват хеш на подкана, ID на шаблон на подкана, версия на подкана, ID на схема, име на инструмента, колекция за извличане, име на маршрут, брой маркери, латентност, нормализиран клас на грешка и състояние на валидиране. Тези полета отговарят на много оперативни въпроси, без да се експортира необработено съдържание.

Необработените подкани и улавянето на завършване трябва да бъдат включени, ограничени във времето, контролирани с достъп и редактирани преди експортиране. Не го активирайте глобално като функция за удобство. Когато е необходимо улавяне на съдържание за производствен инцидент, прикачете флаг за отстраняване на грешки към тесен набор от заявки, насочете тези проследявания към ограничен бекенд и задайте кратък прозорец за задържане.

Идентификаторите за хеширане не са автоматично анонимизиране. Ако входното пространство е малко или предвидимо, хешираните стойности могат да бъдат обърнати чрез предположение. За чувствителни идентификатори на клиенти или потребители помислете за изтриване, сурогатни идентификатори, групиране, съкращаване или ключово хеширане със строги контроли на ключовете. Използвайте хешове предимно за стабилна корелация, когато рискът е разбран, а не като общ отговор за поверителност.

Налагане на поверителност в Collector

Указанията на OpenTelemetry казват, че чувствителните данни трябва да се обработват преди експортиране. Колекторът може да премахва, хешира, филтрира, редактира или трансформира телеметрични атрибути с помощта на процесори като атрибути, филтриране, редактиране и трансформиране. Това прави Collector втора линия на защита след самата апаратура на шлюза.

Един практичен тръбопровод на Collector трябва да използва разрешен списък за атрибути с нисък риск, да изтрива необработени полета за подкана и отговор по подразбиране, да маскира стойности, съответстващи на блокирани шаблони, и да насочва следи с по-висока чувствителност отделно, когато улавянето на съдържание е изрично активирано. Процесорът на атрибути OpenTelemetry Collector поддържа действия като изтриване и хеширане. Процесорът за редактиране е проектиран да изтрива атрибути, които не са в разрешен списък, и да маскира стойности, съответстващи на блокирани шаблони.

Например, шлюзът може да избегне излъчването на необработено съдържание по подразбиране, докато Collector все още изтрива атрибути като llm.prompt.raw, llm.completion.raw, provider.api_key, authorization и cookie, ако се появят поради грешка или интеграция на библиотека. Отнасяйте се към това като към задълбочен контрол на защитата, а не като причина за небрежно излъчване на опасни данни.

Повторни опити за инструмент, резервни варианти и валидиране поотделно

Повторните опити и резервни варианти често са невидими в сборните API показатели. Тази невидимост причинява два оперативни проблема. Първо, забавянето може да се влоши, защото успешният отговор може да скрие множество неуспешни опити.Второ, разходите могат да се повишат, тъй като една заявка на потребител може да създаде няколко извиквания на модел нагоре по веригата.

Всеки интервал от опити на доставчик трябва да включва номер на опит, причина за повторен опит, избран доставчик, избран модел, бюджет за изчакване, латентност, използване на токен, когато е наличен, и резултат. Ако възникне резервен вариант, резервният диапазон трябва да идентифицира първоначалната политика за маршрута, причината за резервния вариант и модела, действително използван за крайния отговор.

Утвърждаването на структурирания изход трябва да бъде собствен интервал или събитие. Идентификационен номер на схемата за улавяне, версия на схемата, резултат от валидиране, брой опити за поправка и крайно състояние. Не съхранявайте пълния невалиден изход по подразбиране. Неуспешното валидиране е оперативно различно от транспортната грешка на доставчика и таблата за управление не трябва да ги замъгляват.

Изградете табла за управление около въпроси, а не доставчици

Неутралната за доставчика наблюдателност трябва да отговаря директно на оперативните въпроси. Полезните табла за управление включват p95 и p99 латентност по модел, доставчик, екип, среда и клас на натоварване; използване на токени от екип и маршрут; степен на отказ по нормализиран клас на грешка; повторете усилването по правилата на маршрута; резервна честота по заявен модел; грешки в контекстния прозорец чрез шаблон за подкана; грешки при валидиране на структуриран изход по схема; и извадкови примери за проследяване за неуспешни, скъпи или бавни заявки.

Поддържайте отчетите за фактуриране и общо използване извън извадковите проследявания. Крайното вземане на проби е полезно за отстраняване на грешки, но може да изкриви общите стойности. Общите суми на токените, броят на заявките и регистрите на разходите трябва да идват от броячи без извадка, регистри на заявки или системи за съгласуване на фактуриране. Следите трябва да обяснят защо е възникнала скъпа или бавна заявка; те не трябва да са единственият източник на финансова истина.

Използване на опашката за проследяване с висока стойност

Процесорът за опашка за извадка на OpenTelemetry Collector може да взема решения за извадка след завършване на обхватите, включително политики, базирани на атрибути и числови стойности. Това е полезно за трафика на LLM, тъй като често знаете дали проследяването е ценно едва след като отговорът приключи.

Запазване на следите за грешки на доставчика, неуспешни валидации, много висока латентност, необичайно скъпо използване на токени, грешки на контекстни прозорци, резервни опити и ръчно маркирани заявки за отстраняване на грешки. Примерен рутинен успешен трафик при по-ниска скорост. Това поддържа следите, които е най-вероятно да обяснят инциденти, като същевременно контролира обема на съхранението.

Разумният модел на политиката е прост: винаги поддържайте грешки, винаги поддържайте заявки над латентност или праг на токена, винаги поддържайте следи с маркери за отстраняване на грешки и правете проби от обикновени успешни заявки по вероятност. Преразгледайте праговете при промени в трафика. Праг, който е полезен по време на ранно приемане, може да бъде твърде нисък, след като производственият трафик нарасне.

Добавяне на договорни тестове за телеметрия

Телеметрията трябва да се тества като API договор, тъй като таблата за управление надолу по веригата, сигналите, контролите на разходите и работните потоци на инциденти зависят от нея. Добавете тестове, които изпълняват представителни заявки за шлюз и потвърждават, че са излъчени необходимите обхвати и атрибути.

Тестовете трябва да потвърдят, че успешната заявка излъчва обхвата на логическата LLM операция, обхвата на опитите на доставчика, заявения модел, модела на отговор, името на доставчика, броя на токените, когато е наличен, метаданните за обхвата на екипа или ключа, версията на правилата за маршрута и окончателното състояние. Тестовете за повторен опит трябва да посочват броя на опитите и причините за повторен опит. Резервните тестове трябва да твърдят както неуспешния опит, така и последния успешен опит за доставчик. Тестовете за валидиране трябва да потвърждават ID на схемата, статус на валидиране и брой опити за поправка.

Тестовете за сигурност са също толкова важни. Уверете се, че необработените ключове на доставчика, заглавките за оторизация, бисквитките, необработените подкани, необработените завършвания и неодобрените клиентски идентификатори отсъстват от експортираната телеметрия.Тези тестове трябва да не успеят да бъдат затворени, когато разработчик добави нов атрибут span, без да го класифицира.

Контролен списък за внедряване

• Договор за атрибут: Дефинирайте задължителни, незадължителни, ограничени и забранени атрибути.
• Йерархия на span: Отделете входящите заявки, логически LLM операции, опити на доставчик, повторни опити, резервни връщания, извиквания за извличане, извиквания на инструменти и валидиране.
• Семантично картографиране: Използвайте атрибути на OpenTelemetry GenAI, където са подходящи, и частни атрибути на шлюза за собственост и контекст на маршрутизиране.
• Политика за поверителност: По подразбиране се използват хешове, идентификатори на шаблони, идентификатори на схеми, имена на инструменти, брой токени, латентност и класове на грешки вместо необработено съдържание.
• Колекционни процесори: Изтриване на забранени полета, редактиране на блокирани шаблони, атрибути с нисък риск в разрешените списъци и отделно маршрутизиране на чувствителни следи.
• Вземане на проби политика: Проследяване на следи с висока стойност и запазване на сборните показатели без извадка.
• Табла за управление: Изграждане на изгледи около забавяне, използване, неуспехи, повторни опити, резервни варианти, валидиране и драйвери за разходи.
• Сигнали: Сигнал за нормализирана грешка класове, изместване на латентността на p99, усилване при повторен опит, пикове на резервни резултати, неуспешни валидации и аномалии на токени.
• Тестове на договори: Уверете се, че е налице необходимата телеметрия и липсва чувствителна телеметрия.

Компромиси, които трябва да решите Изрично

Инструментите на ниво шлюз предоставят последователни метаданни бързо, но могат да пропуснат специфичен за приложението контекст, освен ако екипите не предават структурирани метаданни на заявка като клиент, работен поток, шаблон за подкана и име на функция. Направете тези метаданни част от договора за заявка за шлюз, вместо да разчитате на регистрационни файлове в свободна форма.

Пълното улавяне на съдържание подобрява отстраняването на грешки и оценката, но увеличава поверителността, сигурността, задържането и тежестта за контрол на достъпа. Много екипи трябва да започнат само с хешове, идентификатори на шаблони, идентификатори на схеми и редактирани извадки.

Неутралните по отношение на доставчика класове грешки правят таблата за управление използваеми в множество модели API, но компресират специфични за доставчика подробности. Съхранявайте необработените кодове за грешка на доставчика само когато е безопасно и ограничавайте достъпа до тях.

Конвенциите на OpenTelemetry GenAI намаляват блокирането, но конвенциите ще продължат да се развиват. Вътрешният картограф ви дава предимствата на стандартизацията, без да позволява изтичане на нестабилни имена на атрибути през кодовата база.

Заключение

Неутралната по отношение на доставчика LLM наблюдаемост не е просто проследяване, добавено към извикванията на модела. Това е оперативен договор на слоя на шлюза: последователни обхвати, нормализирани метаданни на модела и доставчика, контекст на собствеността, използване на токена, видимост за повторен опит и резервен вариант, контроли за поверителност, правила за вземане на проби и тестове, които предотвратяват изтичането на чувствителни данни.

Започнете с шлюза, защото той вече вижда най-важните решения: кой е направил заявката, коя политика я е насочила, кой доставчик я е обслужил, какво струва в жетони, колко време е отнело, дали е работила логиката за възстановяване и какво е неуспешно. След като тази основа е стабилна, екипите за приложения могат да добавят по-богат контекст на работния процес, без всеки екип да измисля своя собствена система за наблюдение на LLM.

Свързано четене

• телеметрия за резервно маршрутизиране