Изследване: Търсене и инспекция на производствени следи
На тази страница
Урокът е пренаписан на 2 ноември 2026 г. въз основа на страниците Send traces и Explore traces на Mistral и SDK
mistralaiверсия 3.7.0: Explorer фокусира върху OpenTelemetry следи, заявени чрез език за търсене с изрази; остарелият методchat_completion_events.searchвече не съществува. Източници: Send traces · Explore traces.
Explorer: Вашият прозорец към продукцията
Trace Explorer е мястото, където търсите, филтрирате и инспектирате всяка следа, преминаваща през Вашите AI приложения. Ще го откриете в Studio под Observability → Traces. Въпреки това, следите няма да се появят там, освен ако първо не ги активирате: проследяването е изключено по подразбиране.
Изпращане на следи
С Python SDK инсталирайте разширението за телеметрия (mistralai[telemetry], версия 2.4.13 или по-нова), след което го активирайте в клиента:
from mistralai.client import Mistral
from mistralai.extra.observability import configure_telemetry
client = Mistral(api_key="your-api-key")
configure_telemetry(client)
От този момент нататък SDK автоматично проследява извикванията на модели, вгражданията, операциите на агенти, FIM завършванията и OCR. Извикванията на Ваши собствени инструменти не се проследяват автоматично: трябва да добавите техните интервали (spans), използвайки трасировчика на SDK.
from mistralai.extra.observability import get_telemetry_tracer
tracer = get_telemetry_tracer(client, "agent-support")
with tracer.start_as_current_span("invoke_agent"):
response = client.chat.complete(
model="mistral-small-latest",
messages=[{"role": "user", "content": "What is the status of order 4521?"}],
)
with tracer.start_as_current_span("execute_tool order_tracking") as span_tool:
span_tool.set_attribute("gen_ai.tool.name", "order_tracking")
span_tool.set_attribute("gen_ai.tool.call.arguments", "4521")
# call your tool here
Другите източници се държат различно: Workflows проследяват всяко изпълнение веднага щом OTEL_ENABLED=true е зададено за услугата, докато Vibe Work се активира чрез административна настройка в Studio. TypeScript SDK предлага configureTelemetry. Обратно, Vibe Code (CLI и Web) и Studio Playground не изпращат следи. Всички източници прикриват част от данните по подразбиране преди експортиране; страницата Data redaction описва подробно тази политика и как да я коригирате.
Какво съдържа една следа
Една следа е дърво от интервали (spans), където всеки интервал представлява операция във веригата:
| Поле | Съдържание |
|---|---|
| Trace ID | Идентификатор за цялата верига на изпълнение |
| Spans | Операции: извиквания на модели, извиквания на инструменти, стъпки на работен поток |
| Duration | Време за всеки интервал и за цялата следа |
| Tokens | Входни и изходни токени за всяко извикване на модел |
| Status | Успех или грешка, включително съобщението за грешка |
| Source | Продукт източник: SDK, Workflows, Vibe Work |
| Tags | Етикети, приложени от SDK и автоматични метаданни, като модела |
Кликването върху следа отваря нейното дърво от интервали; всеки интервал се разгъва, за да покаже вход, изход, латентност и токени.
Езикът за търсене
Explorer приема език за изрази: условия върху полетата на следите, комбинирани с AND, OR и NOT.
| Категория | Оператори | Пример |
|---|---|---|
| Сравнение | =, !=, <, <=, >, >= | duration_ns > 5000000000 |
| Шаблон | LIKE, ILIKE, NOT LIKE | service_name LIKE '%agent%' |
| Подниз | CONTAINS, NOT CONTAINS | service_name CONTAINS 'sdk' |
| Регулярен израз | REGEXP, NOT REGEXP | service_name REGEXP '^my-' |
| Диапазон | BETWEEN ... AND ... | duration_ns BETWEEN 1000000 AND 5000000000 |
| Списък | IN (...), NOT IN (...) | status_code IN ('Error', 'Ok') |
| Наличие | EXISTS, NOT EXISTS | error_message EXISTS |
Наличните полета включват service_name, status_code (Ok или Error), duration_ns (в наносекунди), error_message, start_time, models_used (списък) и всеки атрибут на интервал, използващ синтаксис с квадратни скоби: span_attributes['gen_ai.request.model']. За списъци, функциите has(models_used, 'mistral-medium-latest'), hasany(...) и hasall(...) допълват CONTAINS.
# Всички неуспешни следи от услуга
service_name = 'agent-support' AND status_code = 'Error'
# Следи, по-дълги от 5 секунди
duration_ns > 5000000000
# Следи, които са извикали конкретен модел
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'
Ако търсенето не върне резултати, премахнете всички условия освен времевия диапазон, след което ги добавете отново едно по едно. Честа грешка е филтрирането за status_code = 'Error', когато повечето следи са успешни.
Заявяване на следи чрез SDK
Можете да изпълнявате същите търсения програмно в рамките на времеви диапазон:
from datetime import datetime, timedelta, timezone
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
now = datetime.now(timezone.utc)
response = client.beta.observability.traces.search(
from_=now - timedelta(days=1),
to=now,
search_expression="service_name = 'agent-support' AND status_code = 'Error'",
page_size=50,
)
for trace in response.traces.results or []:
print(f"{trace.trace_id} {trace.root_span_name} : {trace.duration_ns / 1e9:.1f} s")
Отговорът използва пагинация на базата на курсор. Справочникът на API документира крайните точки Traces и Spans (търсене, единична следа, възможни полета и стойности, интервали на следа).
Добавяне на интервали към набор от данни
Explorer служи и като отправна точка за тестови наборове от данни. От дадена следа, менюто на интервала предлага Add span to dataset; в изгледа Spans можете да изберете до 500 наведнъж и да картографирате всяко поле на интервала към поле на запис. Тази функция се отнася до офлайн оценявания, запазени за организации от ниво Enterprise (Урок 15).
Ключови изводи
- Проследяването е изключено по подразбиране:
configure_telemetry(client)го активира за Python SDK, аOTEL_ENABLED=trueза Workflows - Извикванията на модели се проследяват автоматично; извикванията на инструменти изискват ръчно проследяване с
get_telemetry_tracer - Explorer филтрира следите, използвайки език за изрази (
service_name,status_code,duration_ns,span_attributes['…']) - SDK предоставя същата възможност за търсене:
client.beta.observability.traces.search(search_expression=...) - Интересните интервали се превръщат в записи от набор от данни с едно кликване или на партиди от 500