Insights로 오류와 사용 패턴 발견하기

Insights로 오류와 사용 패턴 발견하기

LangSmith Insights로 트레이스를 자동으로 분석하고, 사용 패턴을 감지하며, 공통 에이전트 동작을 식별하고, 수동 트레이스 검토 없이 실패 모드를 표면화해요.

Insights는 트레이스를 자동으로 분석해 사용 패턴, 공통 에이전트 동작, 실패 모드를 감지하므로 수천 개의 트레이스를 수동으로 검토할 필요가 없어요.

Insights는 계층적 분류(hierarchical categorization)를 사용해 데이터를 이해하고 실행 가능한 추세를 강조해요.

참고: Insights는 LangSmith Plus 및 Enterprise 플랜에서 사용할 수 있어요.

출처: 문서

본문

사전 요구사항

• 워크스페이스에서 Insights용으로 설정된 모델 구성.
• LangSmith에서 규칙을 만들 권한(새 Insights Report 생성에 필요).
• LangSmith에서 트레이싱 프로젝트를 볼 권한(기존 Insights Report 보기에 필요).

첫 Insights Report 생성

<Tip>작업을 [수동으로 구성](#작업-구성하기)하려면 Manual 모드로 전환해요.</Tip>

그러면 백그라운드 Insights Report가 시작돼요. Report는 완료하는 데 최대 30분이 걸릴 수 있어요.

`generate_insights()`를 호출하면 SDK가 다음을 수행해요:

1. 채팅 기록을 새 LangSmith 프로젝트에 트레이스로 업로드해요.
2. 업로드된 트레이스에 대해 Insights Report를 생성해요.
3. [LangSmith UI](https://smith.langchain.com)에 결과 링크를 반환해요.

<CodeGroup>
  ```python Python
  import os
  from langsmith import Client

  client = Client()

  chat_histories = [
      [
          {"role": "user", "content": "how are you"},
          {"role": "assistant", "content": "good!"},
      ],
      [
          {"role": "user", "content": "do you like art"},
          {"role": "assistant", "content": "only Tarkovsky"},
      ],
  ]

  report = client.generate_insights(
      chat_histories=chat_histories,
      name="Customer Support Topics - March 2024",
      instructions="What are the main topics and questions users are asking about?",
      openai_api_key=os.environ["OPENAI_API_KEY"],  # optional if already set as workspace secret
  )

  # client.poll_insights(report=report)
  ```
</CodeGroup>

참고: 1,000개 스레드에 대한 인사이트 생성은 OpenAI 모델로는 보통 $1.00-$2.00, 현재 Anthropic 모델로는 $3.00-$4.00의 비용이 들어요. 비용은 샘플링된 스레드 수와 각 스레드의 크기에 따라 달라져요.

결과 이해하기

작업이 완료되면 Insights Report 테이블이 있는 Insights 탭으로 이동할 수 있어요. 각 Report에는 트레이싱 프로젝트의 특정 트레이스 샘플에 대해 생성된 인사이트가 포함돼 있어요.

작업을 클릭하면 자동 생성된 카테고리 집합으로 구성된 트레이스를 볼 수 있어요.

카테고리와 하위 카테고리를 드릴다운해 기본 트레이스, 피드백, 런 통계를 볼 수 있어요.

경영진 요약 (Executive summary)

각 보고서 상단에는 트레이스에서 발견된 가장 중요한 패턴을 표면화하는 경영진 요약이 있어요. 여기에는 다음이 포함돼요:

• 각 패턴이 나타나는 빈도를 백분율로 보여주는 핵심 결과.
• 에이전트가 질문에 특히 관련이 있다고 식별한 트레이스에 대한 클릭 가능한 참조(예: #1, #2, #3).

최상위 카테고리

트레이스는 데이터의 가장 광범위한 패턴을 나타내는 최상위 카테고리로 자동 그룹화돼요.

분포 막대는 각 패턴이 발생하는 빈도를 보여주므로, 예상보다 많거나 적게 발생하는 동작을 쉽게 발견할 수 있어요.

각 카테고리는 간단한 설명과 포함된 트레이스에 대한 집계된 지표를 표시해요:

• 일반적인 트레이스 통계 (오류율, 지연 시간, 비용 등)
• 평가기의 피드백 점수
• 작업의 일부로 추출된 속성

하위 카테고리

카테고리를 클릭하면 하위 카테고리로의 분류가 표시되는데, 이는 해당 트레이스 카테고리의 상호작용 패턴을 더 세밀하게 이해하게 해 줘요.

Chat Langchain 예시에서 Data & Retrieval 아래에 Vector Stores와 Data Ingestion 같은 하위 카테고리가 있어요.

개별 트레이스

클릭하여 트레이스 테이블을 보면 각 카테고리 또는 하위 카테고리에 할당된 트레이스를 볼 수 있어요. 거기서 아무 트레이스나 클릭해 전체 대화 세부 정보를 볼 수 있어요.

작업 구성하기

자동 생성 흐름을 사용하거나 수동으로 구성해 Insights Report를 만들 수 있어요.

구성 자동 생성

1. New Insights를 열고 Auto 토글이 활성화되어 있는지 확인해요.
2. 에이전트의 목적, 배우고 싶은 것, 트레이스가 구조화되는 방식에 대한 자연어 질문에 답해요. Insights는 답변을 초안 구성(작업 이름, 요약 프롬프트, 속성, 샘플링 기본값)으로 변환해요.
3. 프로바이더를 선택한 다음, Generate config를 클릭해 미리 보거나 Run job을 클릭해 즉시 시작해요.

유용한 컨텍스트 제공하기

최상의 결과를 위해 각 프롬프트에 Insights가 필요로 하는 컨텍스트 — 무엇을 배우려는지, 어떤 신호나 필드가 가장 중요한지, 이미 유용하지 않다고 아는 것 — 를 주는 문장을 두세 개 작성해요. 에이전트가 무엇을 하는지와 트레이스가 어떻게 구조화되는지에 대해 명확할수록, Insights는 데이터에 대해 어떻게 추론하는지와 일치하는 특정하고 실행 가능한 방식으로 예제를 더 잘 그룹화할 수 있어요.

트레이스 설명하기

데이터가 어떻게 구성되는지 설명해요: 단일 런인가 아니면 다중 턴 대화인가? 어떤 입력과 출력이 핵심 정보를 담고 있는가? 이는 Insights가 중요한 것에 초점을 맞춘 요약 프롬프트와 속성을 생성하는 데 도움이 돼요. 필요하다면 요약 프롬프트 섹션에서 변수를 직접 지정할 수도 있어요.

모델 선택

Insights는 두 개의 모델을 사용해요:

• 사고 모델 (Thinking model): 클러스터링 단계 수행 (더 유능하고 비용이 높음).
• 요약 모델 (Summarization model): 트레이스별 요약 생성 (더 빠르고 저렴함).

두 모델 모두 워크스페이스에 구성된 프로바이더에서 선택돼요. 모델 구성에서 특정 모델이 Insights용으로 활성화된 경우 개별 선택할 수 있어요. 개별 모델이 구성되지 않았다면 프로바이더(OpenAI 또는 Anthropic)를 선택하고 Insights가 해당 프로바이더의 기본 모델을 사용해요.

최상의 결과를 위해 두 역할 모두 같은 프로바이더의 모델을 사용해요.

수동 구성

수동 구성은 더 많은 제어를 제공해요 — 예를 들어 데이터를 그룹화할 카테고리를 미리 정의하거나 특정 피드백 점수 및 필터와 일치하는 트레이스를 대상으로 지정할 수 있어요.

트레이스 선택

• 샘플 크기: 분석할 최대 트레이스 수 (1,000 제한).
• 시간 범위: 이 시간 범위에서 트레이스가 샘플링돼요.
• 필터: 추가 트레이스 필터. 필터를 조정하면 기준과 일치하는 트레이스 수를 볼 수 있어요.

카테고리

기본적으로 최상위 카테고리는 기본 트레이스에서 하향식(bottom-up)으로 자동 생성돼요.

경우에 따라 관심 있는 특정 카테고리를 미리 알고 있으며 작업이 트레이스를 해당 사전 정의 카테고리에 버킷팅하기를 원할 수 있어요.

구성의 Categories 섹션은 사용할 최상위 카테고리의 이름과 설명을 열거해 이를 수행할 수 있게 해 줘요.

하위 카테고리는 여전히 알고리즘이 사전 정의된 최상위 카테고리 내에서 자동 생성해요.

작업이 완료되면 발견된 최상위 카테고리가 구성에 자동으로 저장돼요 — 단, 구성에 사전 정의된 카테고리가 없는 경우에만요. 이는 후속 예약 실행이 일관성을 위해 해당 카테고리를 재사용함을 의미해요.

요약 프롬프트

작업의 첫 단계는 모든 트레이스에 대한 간단한 요약을 만드는 것이에요. 그런 다음 이 요약을 분류해요.

요약에서 올바른 정보를 추출하는 것은 유용한 카테고리를 얻는 데 필수적이에요.

이 요약을 생성하는 데 사용되는 프롬프트를 편집할 수 있어요. 프롬프트를 편집할 때 고려할 두 가지:

• 요약 지침: 트레이스 요약에 없는 정보는 생성되는 카테고리에 영향을 미치지 않으므로, 각 트레이스에서 추출하는 것이 중요한 정보에 대한 명확한 지침을 제공해야 해요.
• 트레이스 내용: 머스태시(mustache) 형식을 사용해 각 트레이스의 어떤 부분이 요약기에 전달되는지 지정해요. 입력과 출력이 많은 대형 트레이스는 비용이 많이 들고 노이즈가 많을 수 있어요. 프롬프트를 트레이스의 가장 관련 있는 부분만 포함하도록 줄이면 결과를 개선할 수 있어요.

각 트레이스의 어떤 부분을 요약기에 보낼지 다음 템플릿 변수를 적어도 하나 사용해 지정해야 해요:

점 표기법을 사용해 중첩 필드에 접근할 수 있어요. 예를 들어 {{run.inputs.foo.bar}}는 마지막 런의 입력에서 foo 내의 bar 필드만 포함해요.

참고: threads가 있는 프로젝트의 경우 Insights는 전체 대화를 분석해요. 각 스레드에서 가장 최근 루트 런만 run.* 변수에 사용돼요. 전체 대화 이력에 접근하려면 all_thread_messages를 사용해요.

속성

요약과 함께 각 트레이스에서 추출할 추가 문자열, 숫자, 불리언 속성을 정의할 수 있어요. 이 속성은 분류 단계에 영향을 미쳐요 — 유사한 속성 값을 가진 트레이스는 함께 분류되는 경향이 있어요. 카테고리별로 이러한 속성의 집계도 볼 수 있어요.

예를 들어 각 트레이스에서 user_satisfied: boolean 속성을 추출해 알고리즘이 긍정적·부정적 사용자 경험을 나누는 카테고리로 향하도록 하고, 카테고리별 평균 사용자 만족도를 볼 수 있을 거예요.

속성 필터링

인사이트를 생성하기 전에 트레이스를 사전 필터링하려면 불리언 속성에 filter_by 파라미터를 사용할 수 있어요. 활성화하면 속성이 true로 평가되는 트레이스만 분석에 포함돼요.

이는 Insights Report를 특정 트레이스 하위 집합에 집중하려 할 때 유용해요. 예를 들어 오류만 분석하거나, 영어 대화만 조사하거나, 특정 품질 기준을 충족하는 트레이스만 포함하려 할 때요.

작동 방식:

• Insights 구성 생성 시 아무 불리언 속성에 "filter_by": true를 추가해요.
• LLM이 요약 중 각 트레이스를 속성 설명에 대해 평가해요.
• 속성이 false이거나 없는 트레이스는 인사이트 생성 전에 제외돼요.

Insights Report 예약

Insights 보고서를 정기적으로 자동 실행하도록 예약해요. 구성 생성 또는 편집 시 Schedule 섹션을 사용해 선택해요:

• Daily: 매일 8:00 UTC에 실행.
• Weekly on Monday: 매주 월요일 8:00 UTC에 실행.
• Custom: 자체 cron 표현식을 입력 (UTC 기준).

각 예약 실행은 저장된 구성을 사용해 새 보고서를 생성해요. 시간 범위는 동적으로 계산돼요. 예를 들어 "last 24 hours"는 실행 시점의 가장 최근 24시간 창을 항상 분석해요.

구성 저장

나중에 재사용하기 위해 Save as 버튼으로 구성을 선택적으로 저장할 수 있어요. 이는 시간이 지남에 따라 Insights Report를 비교해 사용자 및 에이전트 행동의 변화를 식별하려 할 때 특히 유용해요.

새 Insights Report를 만들 때 창 왼쪽 상단 드롭다운에서 이전에 저장된 구성을 선택할 수 있어요.

더 알아보기 (Learn more)

• 모델 구성
• Smith Python SDK
• 가격 플랜