트레이스 필터링

트레이스 필터링 (ClickHouse)

ClickHouse로 구동되는 LangSmith 트레이싱 프로젝트에서 필터 막대, 필터 단축키, 저장된 필터를 사용해 스레드, 트레이스, 런을 필터링해요.

트레이싱 프로젝트는 스레드, 트레이스, 런에 걸쳐 많은 양의 데이터를 축적할 수 있어요. LangSmith의 필터링 도구를 사용하면 해당 데이터를 정확하게 탐색하고 분석할 수 있어요.

참고: 트레이싱 프로젝트에는 두 가지 필터링 경험이 있어요. 프로젝트 상단에서 어느 것이 적용되는지 확인하세요:

왼쪽에 범위 선택기가 있는 단일 검색 막대: 트레이스 필터링 참조.

필터 칩을 만드는 Add filter 버튼: 트레이스 필터링 (ClickHouse) 참조.

이 페이지는 다음을 다룹니다:

필터 막대와 Filter Shortcuts 패널에서 필터 적용
속성, 전체 텍스트 콘텐츠, 키-값 쌍으로 필터링
필터 구성 저장 및 복사
Details 보기 내에서 필터링
루트 또는 하위 런 속성 필터링을 위한 고급 필터

API 또는 SDK를 통해 프로그래밍 방식으로 분석용 데이터를 내보내는 경우, 대신 트레이스 내보내기 가이드를 참조해요.

출처: 문서

본문

필터 생성 및 적용

런 속성으로 필터링

트레이싱 프로젝트에서 데이터를 필터링하는 두 가지 방법이 있어요:

필터 (Filters): Tracing 프로젝트 페이지 왼쪽 상단에 있어요. 여기서 필터 기준을 구성하고 관리해요.
- 첫 번째 드롭다운은 기본 보기와 저장된 보기를 필터링해요.
- Threads, Traces, Runs로 빠른 필터.
- Add filter는 속성 또는 전체 텍스트 검색을 기반으로 필터를 구성할 수 있게 해요.
Filter Shortcuts: Tracing 프로젝트 페이지 오른쪽 사이드바에 있어요. 필터 단축키 막대는 프로젝트 런에서 가장 자주 발생하는 속성에 기반한 필터에 빠르게 접근할 수 있게 해 줘요.

필터 연산자

사용 가능한 필터 연산자는 필터링 중인 속성의 데이터 타입에 따라 달라져요. 일반적인 연산자 개요는 다음과 같아요:

is: 필터 값과 정확히 일치
is not: 필터 값에 대한 부정 일치
contains: 필터 값에 대한 부분 일치
does not contain: 필터 값에 대한 부정 부분 일치
is one of: 목록의 값 중 하나와 일치
> / <: 숫자 필드에서 사용 가능

특정 필터링 기법

런(스팬) 필터링

런(스팬)을 필터링하려면 기본값을 Traces에서 Runs로 변경해요. 예를 들어 런 이름(run name)이나 런 유형(run type)으로 필터링하려면 이렇게 해요.

런 메타데이터와 태그도 필터링에 유용해요. 이는 파이프라인의 모든 부분에 걸친 좋은 태깅에 의존해요. 자세한 내용은 트레이스에 메타데이터 및 태그 추가를 참조해요.

필터를 더 지정할수록 각 필터를 개별적으로 클릭해 검색 중인 속성을 업데이트할 수 있어요.

입력 및 출력 기반 필터링

스레드, 트레이스 또는 런의 입력과 출력에 포함된 콘텐츠를 기반으로 트레이싱 데이터를 필터링할 수 있어요.

입력이나 출력을 필터링하려면 Full-Text Search 필터를 사용할 수 있는데, 이는 두 필드 중 하나에서 키워드를 일치시켜요. 더 타겟팅된 검색을 위해 {} Input 또는 Output 필터를 사용할 수 있으며, 이는 각각 해당 필드의 콘텐츠만 일치시켜요.

참고: 성능을 위해 LangSmith는 전체 텍스트 검색용 데이터 최대 250자를 인덱싱해요. 검색 쿼리가 이 한도를 초과하면 Input/Output 키-값 검색을 사용하는 것을 권장해요.

또한 다음 방식으로 제공된 모든 용어를 일치시키는 여러 검색어를 지정할 수 있어요:

Full-Text Search로 공백으로 구분된 여러 용어 포함.
첫 필터를 추가한 후 버튼으로 여러 필터 추가.

LangSmith는 텍스트를 분할하고 어떤 순서로든 부분 키워드 일치를 매칭해요. LangSmith는 검색에서 일반적인 중지 단어를 제외해요(nltk 중지 단어 목록 및 몇 가지 다른 일반 JSON 키워드 포함).

참고: 인덱싱되려면 토큰이 최소 2자 이상이어야 해요. 단일 문자 토큰(예: a, x)은 검색에서 제외돼요.

LangSmith filter bar showing full-text search and input/output filters with example search terms for python, tensorflow, embedding, fine, and tune

이미지의 필터를 기반으로 시스템은 입력 또는 출력에서 python과 tensorflow를, 입력에서 embedding을, 출력에서 fine과 tune을 검색해요.

필터 경로에서 필요에 따라 필터를 제거하면 나머지 필터로 검색이 넓어져요.

입력 / 출력 키-값 쌍 기반 필터링

전체 텍스트 검색 외에도 입력과 출력의 특정 키-값 쌍을 기반으로 필터링할 수 있어요. 특히 구조화된 데이터를 다룰 때 더 정밀한 필터링을 허용해요.

참고: LangSmith는 데이터를 체계적이고 검색 가능하게 유지하기 위해 런당 최대 100개의 고유 키를 인덱싱해요. 각 키는 값당 250자라는 문자 제한도 있어요. 데이터가 이러한 한도를 초과하면 텍스트가 인덱싱되지 않아요. 이는 빠르고 안정적인 성능을 보장하는 데 도움이 돼요.

키-값 쌍을 기반으로 필터링하려면, 예를 들어 다음 입력을 일치시키려면:

{
  "input": "What is the capital of France?"
}

Add filter를 선택해요.
첫 번째 드롭다운에서 Input을 선택하고 두 번째 드롭다운으로 Key를 유지한 채 키로 input을 선택해요.
+ Value를 클릭하고 값으로 What is the capital of France?를 입력해요.

점 표기법을 사용해 중첩 키 이름을 선택해 중첩 키도 일치시킬 수 있어요. 예를 들어 출력의 중첩 키를 일치시키려면:

{
  "documents": [
    {
      "page_content": "The capital of France is Paris",
      "metadata": {},
      "type": "Document"
    }
  ]
}

Output Key를 선택하고 키로 documents.page_content를 입력한 다음 값으로 The capital of France is Paris를 입력해요. 이렇게 하면 지정된 값과 중첩 키 documents.page_content가 일치해요.

보다 복잡한 쿼리를 만들기 위해 여러 키-값 필터를 추가할 수 있어요. 오른쪽의 Filter Shortcuts를 사용해 일반적인 키-값 쌍을 기반으로 빠르게 필터링할 수도 있어요:

LangSmith filter shortcuts panel showing quick access to common key-value pair filters

예시: 도구 호출 필터링

특정 도구 호출이 포함된 트레이스를 검색하고 싶은 경우가 흔해요. 도구 호출은 일반적으로 LLM 런의 출력에 표시돼요. 도구 호출을 필터링하려면 Output Key 필터를 사용해요.

이 예시가 도구 호출을 필터링하는 방법을 보여주지만, 같은 로직을 출력의 모든 키-값 쌍 필터링에 적용할 수 있어요.

이 경우 필터링하고 싶은 출력이 다음과 같다고 가정해 볼게요:

{
  "generations": [
    [
      {
        "text": "",
        "type": "ChatGeneration",
        "message": {
          "lc": 1,
          "type": "constructor",
          "id": [],
          "kwargs": {
            "type": "ai",
            "id": "run-ca7f7531-f4de-4790-9c3e-960be7f8b109",
            "tool_calls": [
              {
                "name": "Plan",
                "args": {
                  "steps": [
                    "Research LangGraph's node configuration capabilities",
                    "Investigate how to add a Python code execution node",
                    "Find an example or create a sample implementation of a code execution node"
                  ]
                },
                "id": "toolu_01XexPzAVknT3gRmUB5PK5BP",
                "type": "tool_call"
              }
            ]
          }
        }
      }
    ]
  ],
  "llm_output": null,
  "run": null,
  "type": "LLMResult"
}

이 예시에서 KV 검색은 각 중첩 JSON 경로를 검색 및 필터링에 사용할 수 있는 키-값 쌍으로 매핑해요.

LangSmith는 이를 다음의 검색 가능한 키-값 쌍 집합으로 분할해요:

키	값
`generations.type`	`ChatGeneration`
`generations.message.type`	`constructor`
`generations.message.kwargs.type`	`ai`
`generations.message.kwargs.id`	`run-ca7f7531-f4de-4790-9c3e-960be7f8b109`
`generations.message.kwargs.tool_calls.name`	`Plan`
`generations.message.kwargs.tool_calls.args.steps`	`Research LangGraph's node configuration capabilities`
`generations.message.kwargs.tool_calls.args.steps`	`Investigate how to add a Python code execution node`
`generations.message.kwargs.tool_calls.args.steps`	`Find an example or create a sample implementation of a code execution node`
`generations.message.kwargs.tool_calls.id`	`toolu_01XexPzAVknT3gRmUB5PK5BP`
`generations.message.kwargs.tool_calls.type`	`tool_call`
`type`	`LLMResult`

특정 도구 호출을 검색하려면 루트 런 필터를 제거한 상태에서 다음 Output Key 검색을 사용할 수 있어요:

generations.message.kwargs.tool_calls.name = Plan

이렇게 하면 tool_calls 이름이 Plan인 루트 및 비루트 런이 모두 일치해요.

키-값 쌍에 대한 부정 필터링

다양한 유형의 부정 필터링을 {x} Metadata, Input, Output 필드에 적용해 결과에서 특정 런을 제외할 수 있어요.

예를 들어 메타데이터 키 phone이 1234567890이 아닌 모든 런을 찾으려면:

Metadata Key 연산자를 is로, Key 필드를 phone으로 설정해요.
Value 연산자를 is not으로, Value 필드를 1234567890으로 설정해요.

이렇게 하면 값이 1234567890이 아닌 phone 메타데이터 키를 가진 모든 런이 일치해요.

특정 메타데이터 키가 없는 런을 찾으려면: Key 연산자를 is not으로 설정해요. 예를 들어 키로 phone을 사용하고 Key 연산자를 is not으로 설정하면 메타데이터에 phone 필드가 없는 모든 런이 일치해요.

특정 키도 없고 특정 값도 없는 런을 필터링할 수도 있어요. 메타데이터에 phone 키도 없고 값이 1234567890인 필드도 없는 런을 찾으려면 Key 연산자를 키 phone으로 is not으로, Value 연산자를 값 1234567890으로 is not으로 설정해요.

마지막으로 특정 키는 없지만 특정 값은 있는 런을 필터링할 수도 있어요. phone 키는 없지만 다른 일부 키에 대한 값 1234567890이 있는 런을 찾으려면 Key 연산자를 키 phone으로 is not으로, Value 연산자를 값 1234567890으로 is로 설정해요.

팁: 부분 문자열 일치를 수행하려면 is not 대신 does not contain 연산자를 사용할 수 있어요.

필터 저장

필터를 저장하면 자주 사용하는 필터 구성을 저장하고 재사용할 수 있어요. 저장된 필터는 특정 트레이싱 프로젝트에 한정돼요.

필터를 구성한 후 Save as 버튼을 클릭해 저장해요. 그러면 필터의 이름과 설명을 지정하는 대화 상자가 나타나요.

필터를 저장하면 보기 드롭다운에서 빠른 필터로 사용할 수 있게 돼요.

저장된 필터 업데이트

드롭다운에서 필터를 선택한 상태에서 필터 파라미터를 변경할 수 있어요. 그런 다음 Save를 클릭해 필터를 업데이트해요.

저장된 필터 삭제

드롭다운의 저장된 필터 옆에 있는 아이콘을 클릭하고 휴지통 아이콘으로 필터를 삭제해요.

필터 복사

구성된 필터를 복사해 동료와 공유하거나, 나중에 재사용하거나, API 또는 SDK에서 프로그래밍 방식으로 런을 조회할 수 있어요.

필터를 복사하려면:

UI에서 필터를 만들어요.
필터 막대에서 아이콘을 클릭해요. 트리 또는 트레이스 필터를 구성했다면 그것들도 복사할 수 있어요.
그러면 LangSmith 쿼리 언어로 된 필터를 나타내는 문자열이 제공돼요. 예: and(eq(is_root, true), and(eq(feedback_key, "user_score"), eq(feedback_score, 1))).

쿼리 언어 구문에 대한 자세한 내용은 Trace query syntax를 참조해요.

Details 보기에서 런 필터링

Details 보기에서도 직접 필터를 적용할 수 있는데, 많은 수의 런이 있는 트레이스를 선별할 때 유용해요. 기본 런 테이블 보기에서 사용할 수 있는 것과 동일한 필터를 여기에서 적용할 수 있어요.

기본적으로 필터와 일치하는 런만 표시돼요. 트레이스 트리의 더 넓은 컨텍스트 내에서 일치하는 런을 보려면 보기 옵션을 "Filtered Only"에서 "Show All" 또는 "Most relevant"로 전환해요.

LangSmith trace view showing filter options with 'Filtered Only', 'Show All', and 'Most relevant' view modes

LangSmith 쿼리 언어에서 원시 쿼리 수동 지정

이전에 구성한 필터를 복사했다면, 향후 세션에서 이 원시 쿼리를 수동으로 적용하고 싶을 수 있어요.

그러려면 Details 보기의 필터 팝오버 하단에서 Switch to raw query를 클릭할 수 있어요. 그런 다음 텍스트 상자에 원시 쿼리를 붙여넣을 수 있어요.

참고: 그러면 해당 쿼리가 기존 쿼리에 추가되지, 덮어쓰지 않아요.

고급 필터

루트의 속성에 대한 런(스팬) 필터링

일반적인 개념은 루트 런이 어떤 속성을 가진 트레이스의 일부인 런을 필터링하는 것이에요. 예는 특정 유형의 럔 중 루트 러에 긍정(또는 부정) 피드백이 연결된 런을 필터링하는 것이에요. 그렇게 하려면:

Threads/Traces/Runs 토글에서 Runs를 클릭해요.
다른 필터 규칙을 추가해요. 그런 다음 필터 드롭다운 하단의 Advanced 필터 링크를 클릭할 수 있어요.
Trace 필터를 추가할 수 있는 모달이 열려요. 이러한 필터는 이미 필터링한 개별 럔들의 모든 상위 럔의 트레이스에 적용돼요.

하위 런이 어떤 속성을 가진 런(스팬) 필터링

특정 유형의 하위 럔을 가진 럔을 검색하고 싶을 수 있어요. 예를 들어 이름이 Foo인 하위 럔이 있는 모든 트레이스를 검색하는 것이에요. Foo가 항상 호출되는 것은 아니지만, 호출되는 경우를 분석하고 싶을 때 유용해요.

Threads/Traces/Runs 토글에서 Runs를 클릭해요.
다른 필터 규칙을 추가해요. 그런 다음 필터 드롭다운 하단의 Advanced 필터 링크를 클릭할 수 있어요.
Tree 필터를 추가할 수 있는 모달이 열려요. 이렇게 하면 지정한 규칙이 이미 필터링한 개별 럔들의 모든 하위 럔에 적용돼요.

예시: 트리에 도구 호출 필터가 포함된 모든 럔 필터링

도구 호출 필터링 예시를 확장해, 트리에 도구 필터 호출이 포함된 모든 럔을 필터링하려면 Advanced 필터 설정에서 tree 필터를 사용할 수 있어요.

트레이스 필터링