> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Weave Op로 자체 버킷(BYOB)의 미디어 참조하기
> 자체 클라우드 버킷에 저장된 이미지와 비디오의 URI를 로깅하면, 바이트 데이터를 Weave로 임포트하지 않고도 Weave 트레이스에서 렌더링할 수 있습니다.
Weave에서 보려는 미디어가 이미 자체 버킷에 저장되어 있다면 이 기법을 사용하세요. 예를 들면 다음과 같습니다.
* 비디오 파이프라인에서 추출한 프레임
* 브라우저 에이전트가 캡처한 스크린샷
* 모델이 S3에 저장한 이미지
이 바이트를 Weave에 다시 업로드하는 대신 객체의 URI를 문자열로 로깅하면, Weave가 버킷에 있는 이미지나 비디오를 인라인으로 렌더링합니다. Weave에는 URI만 전송되고 바이트는 버킷에 그대로 남습니다. 2GB 비디오를 로깅하든 그 경로만 로깅하든 비용은 같습니다.
이 방식은 바이트를 읽어 Weave에 저장하는 [Content API](/ko/products/wandb/weave/guides/core-types/media#contents-api) 기반 미디어 로깅과는 다릅니다.
이 기능은 Weave 전용 기능으로, W\&B 아티팩트 및 run 저장소를 뒷받침하는 [플랫폼 BYOB(Secure Storage Connector)](/ko/products/wandb/platform/hosting/data-security/secure-storage-connector)와는 별개입니다. 레퍼런스 미디어 버킷은 팀 단위로 설정하며, 읽기 액세스 권한만 있으면 됩니다.
작동 방식
레퍼런스 미디어 렌더링은 다음 세 단계로 작동합니다.
1. 미디어 객체를 버킷에 저장합니다. 예: `s3://[YOUR-BUCKET]/frames/000123.png`
2. 해당 URI를 트레이스 내 원하는 위치에 문자열 값으로 로깅합니다. Op의 입력이나 출력, 에이전트의 도구 결과 어디든 가능하며, 필드 이름은 상관없습니다.
3. 트레이스를 열면 Weave가 URI를 유효 기간이 짧은 [사전 서명된 URL](/ko/products/wandb/platform/hosting/data-security/presigned-urls)로 변환한 뒤 인라인으로 렌더링합니다. 렌더링 방식은 파일 확장자에 따라 달라집니다. 일반적인 이미지 형식(예: `.png`, `.jpg`, `.gif`)과 비디오 형식(예: `.mp4`, `.mov`, `.webm`)은 인라인으로 렌더링되고, 그 밖의 형식은 다운로드 링크로 표시됩니다.
Weave는 팀에 등록된 버킷을 가리키는 URI만 변환합니다. 지원되는 스킴은 `s3://`와 `gs://`입니다.
사전 요구 사항
* 이 기능은 [W\&B Multi-tenant Cloud](/ko/products/wandb/platform/hosting/hosting-options/multi_tenant_cloud)에서 지원되며, [Dedicated Cloud](/ko/products/wandb/platform/hosting/hosting-options/dedicated-cloud) 및 [Self-Managed](/ko/products/wandb/platform/hosting/hosting-options/self-managed) v0.84.0 이상에서는 프리뷰로 제공됩니다.
* CoreWeave Forge 계정과 [API 키](https://forge.coreweave.com/settings#apikeys)가 필요합니다.
* 직접 관리하는 클라우드 저장소 버킷(S3 또는 GCS)이 필요하며, 버킷에 객체가 하나 이상 있어야 합니다.
* 조직 관리자 권한이 필요합니다. 레퍼런스 버킷을 추가하려면 조직에서 팀을 생성하는 것과 동일한 권한이 있어야 합니다.
W\&B에 버킷 읽기 액세스 권한을 부여하고, 브라우저가 CORS를 통해 객체를 가져올 수 있도록 허용하세요.
트레이스를 볼 때 W\&B는 참조된 각 객체에 대해 유효 기간이 짧은 다운로드 URL을 사전 서명합니다. 사전 서명이 정상적으로 이루어지도록 W\&B 인테그레이션 주체에 버킷 읽기 액세스 권한을 부여하세요. 이 권한은 인라인 렌더링에 사용되는 읽기 전용 액세스입니다.
1. W\&B 인테그레이션 주체에 `s3:GetObject` 권한을 부여하는 버킷 정책을 적용하세요. 다음 내용을 `bucket-policy.json`으로 저장하고, `[YOUR-BUCKET]`을 버킷 이름으로 바꾸세요.
```json lines theme={"system"}
{
"Version": "2012-10-17",
"Id": "WandBAccess",
"Statement": [{
"Sid": "WandbAccess",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::725579432336:role/WandbIntegration"},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::[YOUR-BUCKET]/*"
}]
}
```
그런 다음 버킷에 적용하세요.
```bash theme={"system"}
aws s3api put-bucket-policy --bucket [YOUR-BUCKET] --policy file://bucket-policy.json
```
2. 앱이 브라우저에서 객체를 가져올 수 있도록 CORS 설정을 적용하세요. 다음 내용을 `cors.json`으로 저장하세요.
```json lines theme={"system"}
{
"CORSRules": [{
"AllowedHeaders": ["*"],
"AllowedMethods": ["GET", "HEAD"],
"AllowedOrigins": ["https://forge.coreweave.com"],
"ExposeHeaders": ["ETag"],
"MaxAgeSeconds": 3000
}]
}
```
그런 다음 버킷에 적용하세요.
```bash theme={"system"}
aws s3api put-bucket-cors --bucket [YOUR-BUCKET] --cors-configuration file://cors.json
```
객체가 고객 관리형 KMS 키로 암호화되어 있다면 해당 키 정책에서도 `arn:aws:iam::725579432336:role/WandbIntegration`에 `kms:Decrypt` 권한을 부여해야 합니다. 버킷 정책만으로는 충분하지 않습니다.
1. W\&B 인테그레이션 서비스 계정에 버킷에 대한 `roles/storage.objectViewer` 역할을 부여하세요. `[YOUR-BUCKET]`을 버킷 이름으로 바꾸세요.
```bash theme={"system"}
gcloud storage buckets add-iam-policy-binding gs://[YOUR-BUCKET] \
--member="serviceAccount:wandb-integration@wandb-production.iam.gserviceaccount.com" \
--role="roles/storage.objectViewer"
```
2. 앱이 브라우저에서 객체를 가져올 수 있도록 CORS 설정을 적용하세요. 다음 내용을 `cors.json`으로 저장하세요.
```json lines theme={"system"}
[{
"origin": ["https://forge.coreweave.com"],
"method": ["GET", "HEAD"],
"responseHeader": ["ETag"],
"maxAgeSeconds": 3000
}]
```
그런 다음 버킷에 적용하세요.
```bash theme={"system"}
gcloud storage buckets update gs://[YOUR-BUCKET] --cors-file=cors.json
```
이제 Weight & Biases에서 버킷의 객체를 읽을 수 있고, UI에서도 브라우저를 통해 해당 객체를 가져올 수 있습니다.
레퍼런스 버킷 등록
Weave가 참조된 URI를 사전 서명하고 표시할 수 있도록 팀 설정에서 버킷을 등록하세요.
1. 팀 설정 페이지(`https://forge.coreweave.com/wandb/[YOUR-TEAM]/settings`)로 이동하세요.
2. **Reference buckets** 섹션에서 **Add bucket**을 선택하세요.
3. 클라우드 제공업체(**AWS** 또는 **Google Cloud**)를 선택하세요.
4. 버킷 이름에는 `s3://` 또는 `gs://` 접두사 없이 `[YOUR-BUCKET]`만 입력하세요.
5. 객체 키에는 버킷에 있는 기존 객체의 키를 입력하세요(예: `photos/cat.png`). 전체 URL이 아닌 객체 키만 입력해야 합니다. W\&B는 이 객체 하나를 조회하여 읽기 액세스 권한이 있는지, CORS가 올바르게 설정되었는지 확인합니다. 이 단계는 액세스 권한만 확인하며, 확인이 끝나면 버킷의 모든 객체에 대해 사전 서명을 사용할 수 있습니다.
6. 저장하지 않고 설정을 검증하려면 **Test connection**을 선택하세요(선택 사항).
7. **Add bucket**을 선택하여 저장하세요.
버킷을 등록하기 전에는 참조된 URI가 렌더링되지 않습니다. 버킷을 등록해야 Weave가 객체를 사전 서명하고 표시할 수 있습니다.
URI를 트레이스에 문자열 값으로 로깅하세요. 값이 버킷 URI인 문자열 필드는 모두 렌더링됩니다. 바이트는 버킷에 그대로 남아 있으므로 별도의 콘텐츠 어노테이션은 필요하지 않습니다. 다음 예시 Op는 버킷에 이미 저장된 이미지에 캡션을 생성하고, 각 URI를 캡션과 함께 로깅합니다. `[YOUR-TEAM]`, `[YOUR-PROJECT]`, `[YOUR-BUCKET]`을 실제 값으로 바꾸세요.
에이전트형 애플리케이션에 레퍼런스 미디어를 추가하려면 [에이전트 span의 레퍼런스 미디어](/ko/products/wandb/weave/guides/tracking/agents-byob-references)를 참조하세요.
```python lines theme={"system"}
import weave
weave.init("[YOUR-TEAM]/[YOUR-PROJECT]")
@weave.op
def caption_image(image_uri: str) -> dict:
caption = my_captioner(image_uri) # 사용 중인 모델 또는 API 호출.
# image_uri는 값에 따라 인라인으로 렌더링됩니다. 필드 이름은 자유롭게 지정할 수 있으며,
# 이미지인지 비디오인지는 확장자(여기서는 .png)로 결정됩니다.
return {"image": image_uri, "caption": caption}
caption_image("s3://[YOUR-BUCKET]/photos/cat.png")
```
```typescript lines theme={"system"}
import * as weave from 'weave';
await weave.init('[YOUR-TEAM]/[YOUR-PROJECT]');
const captionImage = weave.op(async function captionImage(imageUri: string) {
const caption = await myCaptioner(imageUri); // 사용 중인 모델 또는 API 호출.
// imageUri는 값에 따라 인라인으로 렌더링됩니다. 필드 이름은 자유롭게 지정할 수 있습니다.
return {image: imageUri, caption};
});
await captionImage('s3://[YOUR-BUCKET]/photos/cat.png');
```
Weave Traces에서 레퍼런스 확인하기
`weave.init()`이 출력하는 링크를 통해 트레이스를 여세요. 레퍼런스된 이미지나 비디오가 **Traces** 뷰에 인라인으로 렌더링됩니다. 객체가 없거나 버킷이 등록되지 않은 경우 등 Weave가 URI를 확인할 수 없으면 URI 문자열이 그대로 표시됩니다.
