대량 내보내기 대상 관리하기

대량 내보내기 대상 관리하기

LangSmith 대량 내보내기를 위한 S3 호환 내보내기 대상을 구성하고 관리해요.

셀프 호스팅, GCP EU, GCP APAC 및 AWS US SaaS의 경우

셀프 호스팅 설치, GCP EU(eu.api.smith.langchain.com), GCP APAC(apac.api.smith.langchain.com) 또는 AWS US(aws.api.smith.langchain.com)의 경우 아래 요청의 LangSmith URL을 업데이트하세요.

대상(destination)은 내보낸 트레이스 데이터를 어디에 쓸지 LangSmith에 알려주는 명명된 구성이에요. 대상을 한 번 만들고, 내보내기 작업을 만들 때 ID로 참조해요. LangSmith는 현재 대상으로 S3 및 모든 S3 호환 버킷(예: GCS 또는 MinIO)을 지원해요. 내보낸 데이터는 Parquet 열 형식으로 작성되며 런 데이터 형식과 동등한 필드를 포함해요.

이 페이지에서는 다음을 다뤄요:

• 대상 설정에 필요한 구성 필드.
• AWS S3 및 GCS에 필요한 버킷 권한.
• 프로바이더별 예시와 자격 증명 옵션을 포함해 API를 통한 대상 생성 방법.
• 대상을 다시 만들지 않고 대상 자격 증명 회전 방법.
• 정적 자격 증명과 AWS IAM 역할 가장 사이 인증 모드 전환 방법.
• 대상 오류 디버깅 방법.

출처: 문서

본문

구성 필드

대상을 구성하려면 다음 정보가 필요해요:

• 버킷 이름 (Bucket Name): 데이터가 내보내질 S3 버킷의 이름.
• 접두사 (Prefix): 데이터가 내보내질 버킷 내의 루트 접두사.
• S3 리전 (S3 Region): 버킷의 리전—AWS S3 버킷에 필요.
• 엔드포인트 URL (Endpoint URL): S3 버킷의 엔드포인트 URL—S3 API 호환 버킷에 필요.
• 액세스 키 (Access Key): S3 버킷의 액세스 키.
• 시크릿 키 (Secret Key): S3 버킷의 시크릿 키.
• 접두사에 버킷 포함 (Include Bucket in Prefix) (선택): 경로 접두사의 일부로 버킷 이름을 포함할지 여부. 기본값은 true. 버킷 이름이 이미 엔드포인트 URL에 있는 가상 호스트형 엔드포인트를 사용할 때는 false로 설정하세요.
• S3 구성 옵션 (config_kwargs_s3, 선택): botocore에 전달되는 고급 S3 주소 지정 방식 및 요청 설정. 가장 흔한 용도는 가상 호스트형 또는 경로형 요청이 필요한 S3 호환 서비스에 addressing_style을 설정하는 것이에요:
  • "virtual": 버킷 이름이 호스트 이름의 일부 (예: bucket.endpoint/key). Volcengine TOS 같은 일부 S3 호환 서비스에 필요.
  • "path": 버킷 이름이 URL 경로의 일부 (예: endpoint/bucket/key).
  • "auto" (기본값): boto3가 엔드포인트를 기반으로 결정.

원하는 S3 호환 버킷을 지원해요. GCS 또는 MinIO 같은 비-AWS 버킷의 경우 엔드포인트 URL을 제공해야 해요.

필요한 권한

backend 및 queue 서비스 모두 대상 버킷에 대한 쓰기 접근이 필요해요:

• backend 서비스는 내보내기 대상이 생성될 때 대상 버킷에 테스트 파일을 쓰려고 시도해요. 권한이 있다면 테스트 파일을 삭제해요 (삭제 접근은 선택적).
• queue 서비스는 대량 내보내기 실행과 파일 업로드를 담당해요.

AWS S3 권한

최소 AWS S3 권한 정책은 다음 권한에 의존해요:

• s3:PutObject (필수): 버킷에 Parquet 파일을 쓸 수 있게 해요.
• s3:DeleteObject (선택): 대상 생성 중 테스트 파일을 정리해요. 이 권한이 없으면 대상 생성 후 파일이 /tmp 디렉터리에 남아요.
• s3:GetObject (선택이지만 권장): 쓰기 후 파일 크기를 검증해요.
• s3:AbortMultipartUpload (선택이지만 권장): 중단된 멀티파트 업로드를 방지해요.

최소 IAM 정책 예시:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

추가 권한이 있는 권장 IAM 정책 예시:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

Google Cloud Storage (GCS) 권한

S3 호환 XML API와 함께 GCS를 사용할 때 다음 IAM 권한이 필요해요:

• storage.objects.create (필수): 버킷에 파일을 쓸 수 있게 해요.
• storage.objects.delete (선택): 대상 생성 중 테스트 파일을 정리해요. 이 권한이 없으면 대상 생성 후 파일이 /tmp 디렉터리에 남아요.
• storage.objects.get (선택이지만 권장): 쓰기 후 파일 크기를 검증해요.

이러한 권한은 "Storage Object Admin" 사전 정의 역할이나 커스텀 역할을 통해 부여할 수 있어요.

대상 생성하기

다음 예시는 cURL을 사용해 대상을 만드는 방법을 보여줘요. 플레이스홀더 값을 실제 구성 세부 정보로 바꾸세요. 자격 증명은 시스템에 암호화된 형태로 안전하게 저장된다는 점에 유의하세요.

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My S3 Destination",
    "config": {
      "bucket_name": "your-s3-bucket-name",
      "prefix": "root_folder_prefix",
      "region": "your aws s3 region",
      "endpoint_url": "your endpoint url for s3 compatible buckets",
      "include_bucket_in_prefix": true // defaults to true, can be omitted
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

반환된 id를 사용해 후속 대량 내보내기 작업에서 이 대상을 참조하세요.

대상을 만드는 동안 오류가 발생하면 대상 오류 디버깅을 참고해 디버깅 방법을 확인하세요.

자격 증명 구성

LangSmith Helm 버전 0.10.34 이상(애플리케이션 버전 0.10.91 이상) 필요

정적 access_key_id와 secret_access_key 외에도 다음 추가 자격 증명 형식을 지원해요:

• 임시 자격 증명(AWS 세션 토큰 포함)을 사용하려면 대량 내보내기 대상을 만들 때 credentials.session_token 키를 추가로 제공하세요.
• (셀프 호스팅 전용): AWS IAM Roles for Service Accounts(IRSA) 같은 환경 기반 자격 증명을 사용하려면 대량 내보내기 대상을 만들 때 요청에서 credentials 키를 생략하세요. 이 경우 표준 Boto3 자격 증명 위치가 라이브러리에서 정의한 순서대로 확인돼요.

AWS S3 버킷

AWS S3의 경우 endpoint_url을 생략하고 버킷의 리전과 일치하는 리전을 제공할 수 있어요.

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My AWS S3 Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "region": "us-east-1"
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

Google GCS XML S3 호환 버킷

Google의 GCS 버킷을 사용할 때는 XML S3 호환 API를 사용해야 하며, 일반적으로 https://storage.googleapis.com인 endpoint_url을 제공해야 해요. 다음은 S3와 호환되는 GCS XML API를 사용할 때의 API 요청 예시예요:

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My GCS Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "endpoint_url": "https://storage.googleapis.com"
      "include_bucket_in_prefix": true // defaults to true, can be omitted
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

자세한 내용은 Google 문서를 참고하세요.

가상 호스트형 주소 지정을 사용하는 S3 호환 버킷

일부 S3 호환 서비스(예: Volcengine TOS)는 버킷 이름이 URL 경로가 아닌 호스트 이름의 일부가 되는 가상 호스트형 주소 지정을 요구해요. addressing_style: "virtual"과 함께 config_kwargs_s3를 사용해 이를 활성화하세요:

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My Volcengine TOS Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "endpoint_url": "https://tos-s3-cn-beijing.volces.com",
      "config_kwargs_s3": {
        "addressing_style": "virtual"
      }
    },
    "credentials": {
      "access_key_id": "YOUR_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_SECRET_ACCESS_KEY"
    }
  }'

가상 호스트형 엔드포인트가 있는 S3 호환 버킷

엔드포인트 URL이 이미 버킷 이름을 포함하고 있다면(가상 호스트형) 경로에서 버킷 이름이 중복되지 않도록 include_bucket_in_prefix를 false로 설정하세요:

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My Virtual-Hosted Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "endpoint_url": "https://my_bucket.s3.us-east-1.amazonaws.com",
      "include_bucket_in_prefix": false
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

대상 자격 증명 회전하기

PATCH /api/v1/bulk-exports/destinations/{destination_id}를 사용해 기존 대상의 자격 증명을 업데이트하세요. 이렇게 하면 대상이나 연관된 대량 내보내기를 다시 만들지 않고도 자격 증명을 회전하거나 교체할 수 있어요. 대상 구성(버킷, 접두사, 리전, 엔드포인트 등)은 변경되지 않으며 자격 증명만 교체돼요.

자격 증명 회전 동작

전환은 즉각적이지 않아요:

• 새 대량 내보내기 런은 PATCH가 완료된 직후부터 업데이트된 자격 증명을 사용해요.
• 이미 실행 중인 대량 내보내기 런은 완료될 때까지 이전 자격 증명을 계속 사용해요.
• 전환 기간 동안 두 자격 증명 세트가 동시에 활성화돼요. 이 기간은 단일 대량 내보내기 런의 최대 런타임까지 지속돼요.

그에 따라 회전을 계획하세요: 진행 중인 모든 런이 완료될 때까지 이전 자격 증명이 유효해야 해요.

요청

curl --request PATCH \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations/{destination_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "credentials": {
      "access_key_id": "YOUR_NEW_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_NEW_SECRET_ACCESS_KEY"
    }
  }'

session_token 필드는 선택이며 임시 자격 증명에 포함할 수 있어요.

필수 권한: bulk-exports:manage.

새 자격 증명을 저장하기 전에 LangSmith는 기존 대상 구성을 사용해 버킷에 테스트 쓰기를 수행해 검증해요. 자격 증명에 충분한 쓰기 권한이 없으면 요청이 400으로 실패해요. 요청이 실패하면 대상 오류 디버깅을 참고하세요.

응답

업데이트된 대상 객체를 반환해요. 자격 증명 값은 절대 반환되지 않으며, 응답에는 credentials_keys 아래 자격 증명 필드 이름만 포함돼요.

{
  "id": "destination-uuid",
  "tenant_id": "tenant-uuid",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-06-01T00:00:00Z",
  "credentials_keys": ["access_key_id", "secret_access_key"]
}

회전 체크리스트

1. 대상 버킷과 접두사에 대한 쓰기 접근으로 클라우드 프로바이더에서 새 자격 증명을 프로비저닝하세요.
2. 새 자격 증명으로 PATCH 엔드포인트를 호출하세요. LangSmith는 저장 전에 검증해요.
3. 진행 중인 모든 대량 내보내기 런이 끝날 때까지(최대 최대 실행 지속 시간 동안) 이전 자격 증명을 활성 상태로 유지하세요.
4. 어떤 런도 사용하지 않게 되면 이전 자격 증명을 폐기하세요.

AWS IAM 역할로 인증하기

AWS IAM 역할 가장을 사용하면 GCP에서 호스팅되는 LangSmith SaaS가 정적 AWS 자격 증명을 저장하지 않고도 S3로 내보낼 수 있어요. 프로덕션 리전에 대한 LangSmith 서비스 계정을 신뢰하는 AWS 역할을 구성한 다음, 대상을 만들거나 업데이트할 때 그 ARN을 제공하세요.

IAM 역할 가장을 사용하려면 credentials 대신 aws_role_arn을 전달하세요.

IAM 역할 가장은 GCP에서 호스팅되는 LangSmith SaaS에서만 사용할 수 있어요. AWS 호스팅 SaaS 또는 셀프 호스팅 배포에서는 사용할 수 없어요.

AWS 역할 만들기

리전의 세 가지 subject ID에서 웹 아이덴티티 페더레이션을 허용하는 신뢰 정책으로 AWS IAM 역할을 만드세요. 역할에 내보내기 버킷에 대한 접근을 부여하세요. LangSmith 리전을 선택해 해당 subject ID를 사용하세요. 각 Terraform 예시는 최소 필수 s3:PutObject 권한을 사용해요:

US:

resource "aws_iam_role" "langsmith_bulk_export" {
  name                 = "langsmith-bulk-export"
  max_session_duration = 43200

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Federated = "accounts.google.com" }
      Action    = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "accounts.google.com:oaud" = "langsmith-bulk-export"
          "accounts.google.com:sub" = [
            "110136955440523778103",
            "116331607438151298187",
            "115251468294701876731",
          ]
        }
      }
    }]
  })

  inline_policy {
    name = "langsmith-bulk-export-s3"
    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [{
        Effect   = "Allow"
        Action   = "s3:PutObject"
        Resource = "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      }]
    })
  }
}

EU:

resource "aws_iam_role" "langsmith_bulk_export" {
  name                 = "langsmith-bulk-export"
  max_session_duration = 43200

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Federated = "accounts.google.com" }
      Action    = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "accounts.google.com:oaud" = "langsmith-bulk-export"
          "accounts.google.com:sub" = [
            "110207823358662523645",
            "115689110758588220909",
            "109691164801275818274",
          ]
        }
      }
    }]
  })

  inline_policy {
    name = "langsmith-bulk-export-s3"
    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [{
        Effect   = "Allow"
        Action   = "s3:PutObject"
        Resource = "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      }]
    })
  }
}

APAC:

resource "aws_iam_role" "langsmith_bulk_export" {
  name                 = "langsmith-bulk-export"
  max_session_duration = 43200

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Federated = "accounts.google.com" }
      Action    = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "accounts.google.com:oaud" = "langsmith-bulk-export"
          "accounts.google.com:sub" = [
            "105923862603785245337",
            "114288557158507552617",
            "116622461022404604716",
          ]
        }
      }
    }]
  })

  inline_policy {
    name = "langsmith-bulk-export-s3"
    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [{
        Effect   = "Allow"
        Action   = "s3:PutObject"
        Resource = "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      }]
    })
  }
}

선택 권한은 AWS S3 권한을 참고하세요.

인증 모드 전환하기

기존 대상을 다시 만들지 않고 정적 자격 증명과 AWS IAM 역할 가장 사이에서 전환하세요. PATCH /api/v1/bulk-exports/destinations/{destination_id}를 사용하세요.

필수 권한: bulk-exports:manage.

LangSmith는 서로 배타적인 두 가지 모드를 지원해요:

• 정적 자격 증명 (credentials): access_key_id와 secret_access_key(임시 자격 증명에는 선택적으로 session_token).
• IAM 역할 가장 (aws_role_arn): LangSmith가 지정된 AWS IAM 역할을 가장하므로 정적 자격 증명이 저장되지 않아요.

AWS IAM 역할 가장으로 전환하려면 PATCH 본문에 aws_role_arn을 제공하세요. 정적 자격 증명으로 전환하려면 credentials를 제공하세요. 두 필드 중 하나라도 존재하고 비어 있지 않으면 LangSmith는 다른 쪽을 지워요.

전환하기 전에 새 인증 구성이 대상 버킷에 대한 쓰기 접근이 있는지 확인하세요. LangSmith는 저장 전에 테스트 쓰기로 구성을 검증해요.

정적 자격 증명에서 AWS IAM 역할로 전환

PATCH 본문에 aws_role_arn을 제공하세요. 이렇게 하면 이전에 저장된 자격 증명이 지워져요.

curl --request PATCH \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations/{destination_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "aws_role_arn": "arn:aws:iam::123456789012:role/LangSmithBulkExportRole"
  }'

AWS IAM 역할에서 정적 자격 증명으로 전환

PATCH 본문에 credentials 객체를 제공하세요. 이렇게 하면 저장된 역할 ARN이 지워져요.

curl --request PATCH \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations/{destination_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: ***' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "credentials": {
      "access_key_id": "YOUR_NEW_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_NEW_SECRET_ACCESS_KEY"
    }
  }'

전환 중 동작

자격 증명 회전에 설명된 것과 동일한 전환 동작이 인증 모드 전환에도 적용돼요:

• 새 대량 내보내기 런은 PATCH가 완료된 직후부터 새 인증 모드를 사용해요.
• 이미 실행 중인 대량 내보내기 런은 완료될 때까지 이전 인증 모드를 계속 사용해요.

새 구성에 충분한 쓰기 권한이 없어 테스트 쓰기가 실패하면 요청은 400을 반환해요.

대상 오류 디버깅

대상 API 엔드포인트는 대상과 자격 증명이 유효하고 버킷에 대한 쓰기 접근이 있는지 검증해요.

오류가 발생했고 이를 디버깅하려면 AWS CLI를 사용해 버킷에 대한 연결을 테스트할 수 있어요. 위의 대상 API에 제공한 것과 동일한 데이터로 CLI를 사용해 파일을 쓸 수 있어야 해요.

AWS S3:

aws configure

# set the same access key credentials and region as you used for the destination
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# List buckets
aws s3 ls /

# test write permissions
touch ./test.txt
aws s3 cp ./test.txt s3://<bucket-name>/tmp/test.txt

GCS 호환 버킷:

--endpoint-url 옵션으로 endpoint_url을 제공해야 해요. GCS의 경우 endpoint_url은 일반적으로 https://storage.googleapis.com이에요:

aws configure

# set the same access key credentials and region as you used for the destination
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# List buckets
aws s3 --endpoint-url=<endpoint_url> ls /

# test write permissions
touch ./test.txt
aws s3 --endpoint-url=<endpoint_url> cp ./test.txt s3://<bucket-name>/tmp/test.txt

일반적인 오류

다음은 일반적인 오류들이에요:

오류	설명
Access denied	블롭 스토어 자격 증명 또는 버킷이 유효하지 않아요. 제공된 액세스 키와 시크릿 키 조합에 지정된 버킷에 접근하거나 필요한 작업을 수행할 권한이 없을 때 발생해요.
Bucket is not valid	지정된 블롭 스토어 버킷이 유효하지 않아요. 버킷이 존재하지 않거나 버킷에 쓰기를 수행할 접근 권한이 부족할 때 발생해요.
Key ID you provided does not exist	제공된 블롭 스토어 자격 증명이 유효하지 않아요. 인증에 사용되는 액세스 키 ID가 유효한 키가 아닐 때 발생해요.
Invalid endpoint	제공된 endpoint_url이 유효하지 않아요. 지정된 엔드포인트가 유효하지 않은 엔드포인트일 때 발생해요. S3 호환 엔드포인트만 지원돼요. 예: GCS는 https://storage.googleapis.com, minio는 https://play.min.io 등. AWS를 사용한다면 endpoint_url을 생략해야 해요.
InvalidBucketName	S3 호환 서비스가 주소 지정 방식 불일치로 요청을 거부했어요. 일부 서비스는 가상 호스트형 주소 지정을 요구해요. 대상 구성에 config_kwargs_s3: {"addressing_style": "virtual"}을 설정해 해결하세요.

더 알아보기 (Learn more)

• 대량 내보내기
• 대량 내보내기 모니터링 및 문제 해결
• 런 데이터 형식