메타데이터 파라미터 레퍼런스

LangSmith에서 LLM 호출을 트레이싱할 때 비용 추적, 모델 구성 비교, 프로바이더 전반의 성능 분석을 위한 ls_ 메타데이터 파라미터를 알려드릴게요.

LangSmith로 LLM 호출을 트레이싱할 때 비용을 추적하고, 모델 구성을 비교하며, 다양한 프로바이더의 성능을 분석하고 싶은 경우가 많습니다. LangSmith의 네이티브 통합(예: LangChain 또는 OpenAI/Anthropic 래퍼)은 이를 자동으로 처리하지만, 커스텀 모델 래퍼와 셀프 호스팅 모델에는 이 정보를 제공하는 표준화된 방법이 필요합니다. LangSmith는 이를 위해 ls_ 메타데이터 파라미터를 사용합니다.

이 메타데이터 파라미터들(모두 ls_ 접두사)은 표준 metadata 필드를 통해 모델 구성과 식별 정보를 전달하게 합니다. 설정되면 LangSmith는 비용을 자동으로 계산하고, UI에 모델 정보를 표시하며, 트레이스 전반에 걸친 필터링과 분석을 지원할 수 있습니다.

ls_ 메타데이터 파라미터를 사용하는 목적:

커스텀 또는 셀프 호스팅 모델의 자동 비용 추적 활성화: 프로바이더와 모델 이름 식별.
온도, 최대 토큰 등 모델 구성 추적: 실험 비교용.
프로바이더 또는 구성 설정으로 트레이스 필터링·분석.
커스텀 에이전트 계측을 위한 Trajectory 뷰 렌더링 커스터마이즈.
중단된 오류 표시: LangSmith가 중단된 실행을 다른 오류와 분리해 렌더링하도록.
각 실행에 사용된 정확한 모델 설정 기록으로 디버깅 개선.

출처: 문서

본문

기본 사용 예제

가장 흔한 사용 사례는 커스텀 모델 래퍼의 비용 추적 활성화입니다. 이를 위해 두 가지 핵심 정보를 제공해야 합니다: 프로바이더 이름(ls_provider)과 모델 이름(ls_model_name). 이 둘은 함께 LangSmith의 가격 데이터베이스와 매칭됩니다.

from langsmith import traceable

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "my_provider",
        "ls_model_name": "my_custom_model"
    }
)
def my_custom_llm(prompt: str):
    return call_custom_api(prompt)

import { traceable } from "langsmith/traceable";

const myCustomLlm = traceable(
  async (prompt: string) => {
    return callCustomApi(prompt);
  },
  {
    run_type: "llm",
    metadata: {
      ls_provider: "my_provider",
      ls_model_name: "my_custom_model"
    }
  }
);

import com.langchain.smith.tracing.RunType;
import com.langchain.smith.tracing.TraceConfig;
import com.langchain.smith.tracing.Tracing;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Function;

Map<String, Object> metadata = new HashMap<>();
metadata.put("ls_provider", "my_provider");
metadata.put("ls_model_name", "my_custom_model");

Function<String, String> myCustomLlm =
    Tracing.traceFunction(
        prompt -> callCustomApi(prompt),
        TraceConfig.builder()
            .runType(RunType.LLM)
            .metadata(metadata)
            .build());

import com.langchain.smith.tracing.RunType
import com.langchain.smith.tracing.TraceConfig
import com.langchain.smith.tracing.traceable

val myCustomLlm =
    traceable(
        { prompt: String -> callCustomApi(prompt) },
        TraceConfig.builder()
            .runType(RunType.LLM)
            .metadata(
                mapOf(
                    "ls_provider" to "my_provider",
                    "ls_model_name" to "my_custom_model",
                ),
            )
            .build(),
    )

이 최소 설정은 LangSmith에게 어떤 모델을 사용하는지 알려주며, 모델이 가격 데이터베이스에 있거나 커스텀 가격을 구성했다면 자동 비용 계산을 가능하게 합니다.

더 포괄적인 추적을 위해 추가 구성 파라미터를 포함할 수 있습니다. 이것은 특히 실험 실행이나 다른 모델 설정 비교 시 유용합니다:

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "openai",
        "ls_model_name": "gpt-5.5",
        "ls_temperature": 0.7,
        "ls_max_tokens": 4096,
        "ls_stop": ["END"],
        "ls_invocation_params": {
            "top_p": 0.9,
            "frequency_penalty": 0.5
        }
    }
)
def my_configured_llm(messages: list):
    return call_llm(messages)

const myConfiguredLlm = traceable(
  async (messages: Array<any>) => {
    return callLlm(messages);
  },
  {
    run_type: "llm",
    metadata: {
      ls_provider: "openai",
      ls_model_name: "gpt-5.5",
      ls_temperature: 0.7,
      ls_max_tokens: 4096,
      ls_stop: ["END"],
      ls_invocation_params: {
        top_p: 0.9,
        frequency_penalty: 0.5
      }
    }
  }
);

import com.langchain.smith.tracing.RunType;
import com.langchain.smith.tracing.TraceConfig;
import com.langchain.smith.tracing.Tracing;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.function.Function;

Map<String, Object> metadata = new HashMap<>();
metadata.put("ls_provider", "openai");
metadata.put("ls_model_name", "gpt-5.5");
metadata.put("ls_temperature", 0.7);
metadata.put("ls_max_tokens", 4096);
metadata.put("ls_stop", Collections.singletonList("END"));

Map<String, Object> invocationParams = new HashMap<>();
invocationParams.put("top_p", 0.9);
invocationParams.put("frequency_penalty", 0.5);
metadata.put("ls_invocation_params", invocationParams);

Function<List<Map<String, String>>, String> myConfiguredLlm =
    Tracing.traceFunction(
        messages -> callLlm(messages),
        TraceConfig.builder()
            .runType(RunType.LLM)
            .metadata(metadata)
            .build());

val myConfiguredLlm =
    traceable(
        { messages: List<Map<String, String>> -> callLlm(messages) },
        TraceConfig.builder()
            .runType(RunType.LLM)
            .metadata(
                mapOf(
                    "ls_provider" to "openai",
                    "ls_model_name" to "gpt-5.5",
                    "ls_temperature" to 0.7,
                    "ls_max_tokens" to 4096,
                    "ls_stop" to listOf("END"),
                    "ls_invocation_params" to
                        mapOf(
                            "top_p" to 0.9,
                            "frequency_penalty" to 0.5,
                        ),
                ),
            )
            .build(),
    )

이 설정으로 나중에 온도로 트레이스를 필터링하고, 다른 max token 설정의 실행을 비교하며, 어떤 구성 파라미터가 최상의 결과를 내는지 분석할 수 있습니다. 이 모든 파라미터는 비용 추적에 필요한 ls_provider와 ls_model_name 쌍을 제외하고 선택 사항입니다.

모든 파라미터

사용자 구성 가능 파라미터

Parameter	Type	Required	Description
`ls_provider`	`string`	Yes*	LLM provider name for cost tracking
`ls_model_name`	`string`	Yes*	Model identifier for cost tracking
`ls_temperature`	`number`	No	Temperature parameter used
`ls_max_tokens`	`number`	No	Maximum tokens parameter used
`ls_stop`	`string[]`	No	Stop sequences used
`ls_invocation_params`	`object`	No	Additional invocation parameters
`ls_agent_type`	`string`	No	Controls how agent runs appear in the Trajectory view: `"root"`, `"subagent"`, or `"middleware"`
`ls_message_view_exclude`	`boolean`	No	Hides the run from the Trajectory view
`ls_is_error_interrupt`	`boolean`	No	Marks an errored run as interrupted when set to `true`

* ls_provider와 ls_model_name은 비용 추적을 위해 함께 제공되어야 합니다

시스템 생성 파라미터

Parameter	Type	Description
`ls_run_depth`	`integer`	Depth in trace tree (0=root, 1=child, etc.) - automatically calculated
`ls_method`	`string`	Tracing method used (e.g., "traceable") - set by SDK

실험 파라미터

Parameter	Type	Description
`ls_example_*`	`any`	Example metadata prefixed with `ls_example_` - added during experiments
`ls_experiment_id`	`string` (UUID)	Unique experiment identifier - added during experiments

파라미터 세부정보

`ls_provider`

Type: string
Required: Yes (with ls_model_name)

역할: LLM 프로바이더를 식별합니다. ls_model_name과 결합되어 LangSmith의 모델 가격 데이터베이스와 매칭해 자동 비용 계산을 가능하게 합니다.

일반 값:

"openai"
"anthropic"
"azure"
"bedrock"
"google_vertexai"
"google_genai"
"fireworks"
"mistral"
"groq"
또는 임의의 커스텀 문자열

사용 시점: 커스텀 모델 래퍼 또는 셀프 호스팅 모델에 대해 자동 비용 추적을 원할 때.

예제:

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "openai",
        "ls_model_name": "gpt-5.5"
    }
)
def my_llm_call(prompt: str):
    return call_api(prompt)

관계:

비용 추적이 동작하려면 ls_model_name 필요.
비용 계산에 토큰 사용량 데이터와 함께 동작.

`ls_model_name`

Type: string
Required: Yes (with ls_provider)

역할: 특정 모델을 식별합니다. ls_provider와 결합되어 자동 비용 계산을 위해 가격 데이터베이스와 매칭됩니다.

일반 값:

OpenAI: "gpt-5.5", "gpt-5.4-mini", "gpt-3.5-turbo"
Anthropic: "claude-sonnet-4-6", "claude-opus-4-8"
커스텀: 임의의 모델 식별자

사용 시점: 자동 비용 추적과 UI에서의 모델 식별을 원할 때.

예제:

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "anthropic",
        "ls_model_name": "claude-3-5-sonnet-20241022"
    }
)
def my_claude_call(messages: list):
    return call_claude(messages)

관계:

비용 추적이 동작하려면 ls_provider 필요.
비용 계산에 토큰 사용량 데이터와 함께 동작.

`ls_temperature`

Type: number (nullable)
Required: No

역할: 사용된 온도 설정을 기록합니다. 추적 전용입니다 — LangSmith 동작에는 영향을 주지 않습니다.

사용 시점: 실험이나 디버깅을 위해 모델 구성을 추적하고 싶을 때.

예제:

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.5",
    "ls_temperature": 0.7
}

관계:

독립적, 추적 전용.
실험 비교를 위해 다른 구성 파라미터와 함께 유용.

`ls_max_tokens`

Type: number (nullable)
Required: No

역할: 사용된 최대 토큰 설정을 기록합니다. 추적 전용입니다 — LangSmith 동작에는 영향을 주지 않습니다.

사용 시점: 실험이나 디버깅을 위해 모델 구성을 추적하고 싶을 때.

예제:

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.5",
    "ls_max_tokens": 4096
}

관계:

독립적, 추적 전용.
실제 토큰 사용량과 결합해 비용 분석에 유용.

`ls_stop`

Type: string[] (nullable)
Required: No

역할: 사용된 stop 시퀀스를 기록합니다. 추적 전용입니다 — LangSmith 동작에는 영향을 주지 않습니다.

사용 시점: 실험이나 디버깅을 위해 모델 구성을 추적하고 싶을 때.

예제:

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.5",
    "ls_stop": ["END", "STOP", "\n\n"]
}

관계:

독립적, 추적 전용.

`ls_invocation_params`

Type: object (any key-value pairs)
Required: No

역할: 특정 ls_ 파라미터에 맞지 않는 추가 모델 파라미터를 저장합니다. 프로바이더 특정 설정을 포함할 수 있습니다.

일반 파라미터: top_p, frequency_penalty, presence_penalty, top_k, seed, 또는 임의의 커스텀 파라미터

사용 시점: 표준 파라미터를 넘어 추가 구성을 추적해야 할 때.

예제:

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.5",
    "ls_invocation_params": {
        "top_p": 0.9,
        "frequency_penalty": 0.5,
        "presence_penalty": 0.3,
        "seed": 12345
    }
}

관계:

독립적, 임의 구성을 저장.

`ls_agent_type`

Type: "root" | "subagent" | "middleware"
Required: No

역할: 커스텀 에이전트형 실행의 메시지가 Trajectory 뷰에 어떻게 나타나는지 제어합니다.

최신 버전의 LangSmith SDK의 트레이싱 래퍼 통합은 필요할 때 이 메타데이터를 자동으로 설정합니다. 커스텀 계측의 경우 에이전트 또는 미들웨어 단계를 나타내는 실행에 이 키를 설정하세요.

값:

"root": 이 실행의 메시지가 메인 Trajectory 뷰에 나타납니다.
"subagent": 이 실행의 메시지가 메인 대화와 분리된 사이드 스레드에 나타납니다.
"middleware": 이 실행의 메시지가 Trajectory 뷰에서 숨겨집니다.

사용 시점: 커스텀 에이전트 계측을 구축하고 Trajectory 뷰가 루트 에이전트, 서브에이전트, 미들웨어를 구별하기를 원할 때.

자세한 내용은 Trajectory 뷰 커스터마이즈를 참고하세요.

관계:

모델 식별 및 비용 추적 메타데이터와 독립적.
에이전트 트레이스에서 실행이 수행하는 역할을 식별해 트레이스 부모-자식 구조를 보완.

`ls_message_view_exclude`

Type: boolean (presence-based)
Required: No

역할: 실행을 Trajectory 뷰에서 숨깁니다. 제외된 실행은 일반 트레이스 뷰, 실행 탐색기, 메트릭에는 계속 나타납니다.

필터는 키의 존재를 확인하며 진실성(truthiness)을 확인하지 않습니다. {LS_MESSAGE_VIEW_EXCLUDE: False}도 실행을 제외합니다. 실행을 포함하려면 키를 완전히 생략하세요.

상수 가져오기: 키는 langsmith(Python 및 JS)에서 LS_MESSAGE_VIEW_EXCLUDE 상수로 내보내지며, 그 값은 문자열 "ls_message_view_exclude"입니다. 오타를 피하려면 상수를 선호하세요. 리터럴 문자열도 동작합니다.

사용 시점: 대화 턴이 아닌 LLM 하위 span(분류 호출, 임베딩 조회, 안전 필터, 라우팅/가드레일 결정 등)에 대해, LangSmith의 다른 곳에서는 계속 보이길 원하지만 대화 기록을 어지럽히고 싶지 않을 때.

예제:

from langsmith import LS_MESSAGE_VIEW_EXCLUDE, traceable

@traceable(run_type="llm", metadata={LS_MESSAGE_VIEW_EXCLUDE: True})
def classify_intent(query: str) -> str:
    return llm.predict(f"Classify: {query}")

Python과 JS 컨텍스트(@traceable, trace, wrap_openai, RunnableConfig, wrapAISDK, RunTree.createChild) 전반의 추가 코드 예제는 Trajectory 뷰에서 실행 제외를 참고하세요.

관계:

모델 식별 및 비용 추적 메타데이터와 독립적.
실행을 완전히 숨기는 대신 역할별로 메시지를 라우팅하는 ls_agent_type을 보완.

`ls_is_error_interrupt`

Type: boolean
Required: No

역할: 오류가 있는 실행에서 true로 설정하면 실행 상태를 error 대신 interrupted로 표시합니다.

사용 시점: 계측이 오류가 중단된 실행(사용자 중단 또는 human-in-the-loop 중단)을 나타낸다고 식별할 수 있고, LangSmith가 이를 다른 오류와 분리해 렌더링하길 원할 때.

예제:

metadata={
    "ls_is_error_interrupt": True
}

관계:

오류를 포함하는 실행에만 영향을 줍니다.
모델 식별 및 비용 추적 메타데이터와 독립적.

`ls_run_depth`

Type: integer
Set by: LangSmith backend (automatic)
Cannot be overridden

역할: 트레이스 트리에서의 깊이를 나타냅니다:

0 = 루트 실행 (최상위)
1 = 직접 자식
2 = 손자
등등

사용 시점: 트레이스 수집 중 자동 계산됩니다. 필터링("루트 실행만 표시")과 UI 시각화에 사용됩니다.

예제 쿼리:

metadata_key = 'ls_run_depth' AND metadata_value = 0

관계:

트레이스 부모-자식 구조에 의해 결정됩니다.
수동으로 설정할 수 없습니다.

`ls_method`

Type: string
Set by: SDK (automatic)

역할: 트레이스를 만든 SDK 메서드(일반적으로 @traceable 데코레이터의 "traceable")를 나타냅니다.

사용 시점: 트레이싱 SDK가 자동으로 설정합니다. 디버깅과 분석에 사용됩니다.

관계:

SDK가 트레이스 생성 방식에 따라 설정.
수동으로 설정할 수 없습니다.

`ls_example_*`

Type: Any (depends on example metadata)
Pattern: ls_example_{original_key}
Set by: LangSmith experiments system (automatic)

역할: 데이터셋에 대한 실험을 실행하면 예제의 메타데이터가 ls_example_로 자동 접두사 처리되어 트레이스에 추가됩니다.

특수 파라미터:

ls_example_dataset_split: 데이터셋 스플릿(예: "train", "test", "validation")

사용 시점: 데이터셋 실험 중. 예제 특성으로 필터링/그룹화할 수 있게 합니다.

예제: 예제에 메타데이터 {"category": "technical", "difficulty": "hard"}가 있으면 트레이스는 다음을 얻습니다:

{
  "metadata": {
    "ls_example_category": "technical",
    "ls_example_difficulty": "hard",
    "ls_example_dataset_split": "test"
  }
}

관계:

예제 메타데이터에서 자동 파생.
트레이스에 수동으로 설정할 수 없습니다.

`ls_experiment_id`

Type: string (UUID)
Set by: LangSmith experiments system (automatic)

역할: 실험 실행의 고유 식별자.

사용 시점: 데이터셋에 대한 실험/평가를 실행할 때 자동 추가됩니다. 같은 실험의 모든 실행을 그룹화하는 데 사용됩니다.

관계:

실행을 특정 실험에 연결.
수동으로 설정할 수 없습니다.

파라미터 관계

비용 추적 의존성

LangSmith가 비용을 자동 계산하려면 여러 파라미터가 함께 동작해야 합니다. 요구사항:

주요 요구사항: ls_provider + ls_model_name

자동 비용 계산을 위해 둘 다 있어야 합니다.
ls_model_name이 없으면 시스템은 ls_invocation_params에서 모델 이름을 확인하는 것으로 폴백합니다.
ls_provider는 가격 데이터베이스의 프로바이더와 일치해야 합니다 (또는 커스텀 가격 사용).

추가 요구사항:

실행에 run_type="llm"이 있어야 합니다 (또는 임의 비용 추적 활성화).
트레이스에 토큰 사용량 데이터가 있어야 합니다 (prompt_tokens, completion_tokens).
모델이 가격 데이터베이스에 있거나 커스텀 가격이 구성되어야 합니다.

폴백 동작: ls_model_name이 메타데이터에 없으면 시스템은 비용 추적을 포기하기 전에 ls_invocation_params에서 "model" 같은 모델 식별자를 확인합니다.

구성 추적 그룹

이 파라미터들은 모델 설정을 추적하는 데 도움이 되지만 LangSmith의 핵심 기능에는 영향을 주지 않습니다:

선택 사항, 독립적으로 동작: ls_temperature, ls_max_tokens, ls_stop

추적/표시용.
LangSmith 동작이나 비용 계산에 영향 없음.
실험 비교와 디버깅에 유용.

인터럽트 렌더링

실행 오류가 error 대신 interrupted로 렌더링되어야 할 때 ls_is_error_interrupt를 true로 설정합니다. 이 파라미터는 오류를 포함하는 실행에만 영향을 줍니다.

Invocation params 특수 케이스

ls_invocation_params 파라미터는 추적 필드이자 폴백 메커니즘의 이중 역할을 합니다:

(부분적으로 독립적, 폴백 역할 포함) ls_invocation_params:

주로 추적용 임의 구성을 저장.
ls_model_name이 없으면 비용 추적의 폴백 역할 가능.
ls_model_name이 있으면 비용 계산에 직접 영향 없음.

시스템 파라미터

이 파라미터들은 LangSmith가 자동 생성하며 수동으로 설정할 수 없습니다:

사용자 설정 불가: ls_run_depth, ls_method, ls_example_*, ls_experiment_id

시스템이 자동 설정.
필터링, 분석, 시스템 추적에 사용.

메타데이터 파라미터로 트레이스 필터링

트레이스에 ls_ 메타데이터 파라미터를 추가한 뒤 API로 프로그래매틱하게 또는 LangSmith UI에서 대화형으로 트레이스를 필터링·검색하는 데 사용할 수 있습니다. 이를 통해 모델, 프로바이더, 구성 설정 또는 트레이스 깊이로 트레이스를 좁힐 수 있습니다.

API 사용

Client 클래스의 list_runs() 메서드(Python) 또는 listRuns() 메서드(TypeScript)를 사용해 메타데이터 값에 기반한 트레이스를 조회합니다. 필터 문법은 동등성 검사, 비교, 논리 연산자를 지원합니다.

from langsmith import Client

client = Client()

# Filter runs by provider
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_provider" AND metadata_value = "openai"'
)

# Filter by specific model
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_model_name" AND metadata_value = "gpt-5.5"'
)

# Filter root runs only (top-level traces)
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_run_depth" AND metadata_value = 0'
)

# Filter by temperature threshold
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_temperature" AND metadata_value > 0.5'
)

import { Client } from "langsmith";

const client = new Client();

// Filter runs by provider
const runsByProvider: any[] = [];
for await (const run of client.listRuns({
  projectName: "my-app",
  filter: 'metadata_key = "ls_provider" AND metadata_value = "openai"'
})) {
  runsByProvider.push(run);
}

// Filter by specific model
const runsByModel: any[] = [];
for await (const run of client.listRuns({
  projectName: "my-app",
  filter: 'metadata_key = "ls_model_name" AND metadata_value = "gpt-5.5"'
})) {
  runsByModel.push(run);
}

// Filter root runs only (top-level traces)
const rootRuns: any[] = [];
for await (const run of client.listRuns({
  projectName: "my-app",
  filter: 'metadata_key = "ls_run_depth" AND metadata_value = 0'
})) {
  rootRuns.push(run);
}

// Filter by temperature threshold
const highTempRuns: any[] = [];
for await (const run of client.listRuns({
  projectName: "my-app",
  filter: 'metadata_key = "ls_temperature" AND metadata_value > 0.5'
})) {
  highTempRuns.push(run);
}

이 예제들은 일반적인 필터링 패턴을 보여줍니다:

프로바이더 또는 모델로 필터링해 특정 모델의 사용 패턴이나 비용 분석.
실행 깊이로 필터링해 루트 트레이스(깊이 0) 또는 특정 중첩 수준의 자식 실행만.
구성으로 필터링해 온도, max tokens 등 다른 설정의 실험 비교.

UI 사용

LangSmith UI에서 필터 문법과 함께 필터/검색 바를 사용합니다:

metadata_key = 'ls_provider' AND metadata_value = 'openai'
metadata_key = 'ls_model_name' AND metadata_value = 'gpt-5.5'
metadata_key = 'ls_run_depth' AND metadata_value = 0

더 알아보기

비용 추적 가이드 — LLM 비용 추적.
트레이스 쿼리 문법 — 필터링 레퍼런스.

메타데이터 파라미터 레퍼런스