W&B Public API를 사용하여 데이터를 내보내거나 가져오세요.
이 기능은 python>=3.8이 필요합니다.
MLFlow에서 데이터 가져오기
W&B는 Experiments, Runs, Artifacts, 메트릭 및 기타 메타데이터를 포함하여 MLFlow에서 데이터를 가져오는 기능을 지원합니다.
종속성 설치:
# 참고: py38+ 버전이 필요합니다.
pip install wandb[importers]
from wandb.apis.importers.mlflow import MlflowImporter
importer = MlflowImporter(mlflow_tracking_uri="...")
runs = importer.collect_runs()
importer.import_runs(runs)
importer.collect_runs()는 MLFlow 서버의 모든 Runs를 수집합니다. 특정 서브셋만 업로드하고 싶다면, 직접 Runs 이터러블을 구성하여 importer에 전달할 수 있습니다.
import mlflow
from wandb.apis.importers.mlflow import MlflowRun
client = mlflow.tracking.MlflowClient(mlflow_tracking_uri)
runs: Iterable[MlflowRun] = []
for run in mlflow_client.search_runs(...):
runs.append(MlflowRun(run, client))
importer.import_runs(runs)
Databricks MLFlow에서 데이터를 가져오는 경우 먼저 Databricks CLI를 설정해야 할 수도 있습니다.이전 단계에서 mlflow-tracking-uri="databricks"를 설정하세요. artifacts=False를 전달할 수 있습니다:
importer.import_runs(runs, artifacts=False)
Namespace를 전달할 수 있습니다:
from wandb.apis.importers import Namespace
importer.import_runs(runs, namespace=Namespace(entity, project))
데이터 내보내기
Public API를 사용하여 W&B에 저장한 데이터를 내보내거나 업데이트하세요. 이 API를 사용하기 전에 스크립트에서 데이터를 로깅해야 합니다. 자세한 내용은 Quickstart를 확인하세요.
Public API 유스 케이스
- 데이터 내보내기: Jupyter Notebook에서 커스텀 분석을 위해 데이터프레임을 가져옵니다. 데이터를 탐색한 후에는 새로운 분석 Run을 생성하고 결과를 로깅하여 발견한 내용(findings)을 동기화할 수 있습니다. 예:
wandb.init(job_type="analysis")
- 기존 Runs 업데이트: W&B Run과 연관되어 로깅된 데이터를 업데이트할 수 있습니다. 예를 들어, 원래 로깅되지 않았던 아키텍처나 하이퍼파라미터 같은 추가 정보를 포함하도록 일련의 Runs 설정을 업데이트하고 싶을 때 유용합니다.
사용 가능한 함수에 대한 자세한 내용은 생성된 레퍼런스 문서를 참조하세요.
API 키 생성
API 키는 해당 머신을 W&B에 인증합니다.
To create an API key, select the Personal API key or Service Account API key tab for details.
Personal API key
Service account API key
To create a personal API key owned by your user ID:
- Log in to W&B, click your user profile icon, then click User Settings.
- Click Create new API key.
- Provide a descriptive name for your API key.
- Click Create.
- Copy the displayed API key immediately and store it securely.
To create an API key owned by a service account:
- Navigate to the Service Accounts tab in your team or organization settings.
- Find the service account in the list.
- Click the action menu (
...), then click Create API key.
- Provide a name for the API key, then click Create.
- Copy the displayed API key immediately and store it securely.
- Click Done.
You can create multiple API keys for a single service account to support different environments or workflows. The full API key is only shown once at creation time. After you close the dialog, you cannot view the full API key again. Only the key ID (first part of the key) is visible in your settings. If you lose the full API key, you must create a new API key.
Store and handle API keys securely
API keys provide access to your W&B account and should be protected like passwords. Follow these best practices:
Recommended storage methods
What to avoid
- Never commit API keys to version control systems such as Git.
- Do not store API keys in plain text configuration files.
- Do not pass API keys on the command line, because they will be visible in the output of OS commands like
ps.
- Avoid sharing API keys through email, chat, or other unencrypted channels.
- Do not hard-code API keys in your source code.
If an API key is exposed, delete the API key from your W&B account immediately and contact support or your AISE.
Environment variables
When using API keys in your code, pass them through environment variables:
export WANDB_API_KEY="your-api-key-here"
Avoid setting the environment variable in line with the command, because it will be visible in the output of OS commands like ps:# Avoid this pattern, which can expose the API key in process managers
export WANDB_API_KEY="your-api-key-here" ./my-script.sh
SDK version compatibility
New API keys are longer than legacy keys. When authenticating with older versions of the wandb or weave SDKs, you may encounter an API key length error.
Solution: Update to a newer SDK version:
-
wandb SDK v0.22.3+
pip install --upgrade wandb==0.22.3
-
weave SDK v0.52.17+
pip install --upgrade weave==0.52.17
If you cannot upgrade the SDK immediately, set the API key using the WANDB_API_KEY environment variable as a workaround.
Run 경로 찾기
Public API를 사용하려면 보통 <entity>/<project>/<run_id> 형태의 Run 경로가 필요합니다. 앱 UI에서 Run 페이지를 열고 Overview 탭을 클릭하여 Run 경로를 확인하세요.
Run 데이터 내보내기
종료되었거나 활성 상태인 Run에서 데이터를 다운로드합니다. 일반적인 용도로는 Jupyter 노트북에서 커스텀 분석을 위해 데이터프레임을 다운로드하거나, 자동화된 환경에서 커스텀 로직을 사용하는 경우가 있습니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
| 속성 | 의미 |
|---|
run.config | 트레이닝 Run의 하이퍼파라미터나 데이터셋 Artifact를 생성하는 Run의 전처리 방법과 같은 Run의 설정 정보 사전(dictionary)입니다. 이를 Run의 입력값으로 생각하면 됩니다. |
run.history() | 손실(loss)과 같이 모델 트레이닝 중에 변하는 값을 저장하기 위한 사전 리스트입니다. run.log() 코맨드는 이 오브젝트에 데이터를 추가합니다. |
run.summary | Run의 결과를 요약하는 정보 사전입니다. 정확도(accuracy) 및 손실(loss)과 같은 스칼라 값이나 대용량 파일이 될 수 있습니다. 기본적으로 run.log()는 요약 값을 로깅된 시계열의 최종값으로 설정합니다. 요약의 내용은 직접 설정할 수도 있습니다. 요약을 Run의 출력값으로 생각하면 됩니다. |
api.flush()를 호출하여 업데이트된 값을 가져오세요.
다양한 Run 속성 이해하기
다음 코드 조각은 Run을 생성하고, 데이터를 로깅한 다음, Run의 속성에 엑세스하는 방법을 보여줍니다:
import wandb
import random
# Run을 생성하고 데이터를 로깅합니다.
with wandb.init(project="public-api-example") as run:
n_epochs = 5
config = {"n_epochs": n_epochs}
run.config.update(config)
for n in range(run.config.get("n_epochs")):
run.log(
{"val": random.randint(0, 1000), "loss": (random.randint(0, 1000) / 1000.00)}
)
run.config
run.summary
{
"_runtime": 4,
"_step": 4,
"_timestamp": 1644345412,
"_wandb": {"runtime": 3},
"loss": 0.041,
"val": 525,
}
샘플링
기본 history 메소드는 메트릭을 고정된 수의 샘플로 샘플링합니다(기본값은 500이며, samples 인수로 변경할 수 있습니다). 대규모 Run의 모든 데이터를 내보내고 싶다면 run.scan_history() 메소드를 사용할 수 있습니다. 자세한 내용은 API 레퍼런스를 참조하세요.
여러 Runs 쿼리하기
DataFrame 및 CSV
MongoDB 스타일
이 예제 스크립트는 Project를 찾고 이름, 설정(configs) 및 요약 통계가 포함된 Runs의 CSV를 출력합니다. <entity>와 <project>를 각각 사용자의 W&B Entity와 Project 이름으로 바꾸세요.import pandas as pd
import wandb
api = wandb.Api()
entity, project = "<entity>", "<project>"
runs = api.runs(entity + "/" + project)
summary_list, config_list, name_list = [], [], []
for run in runs:
# .summary에는 정확도와 같은 메트릭에 대한
# 출력 키/값이 포함되어 있습니다.
# 대용량 파일을 제외하기 위해 ._json_dict를 호출합니다.
summary_list.append(run.summary._json_dict)
# .config에는 하이퍼파라미터가 포함되어 있습니다.
# _로 시작하는 특수 값을 제거합니다.
config_list.append({k: v for k, v in run.config.items() if not k.startswith("_")})
# .name은 Run의 읽기 쉬운 이름입니다.
name_list.append(run.name)
runs_df = pd.DataFrame(
{"summary": summary_list, "config": config_list, "name": name_list}
)
runs_df.to_csv("project.csv")
run.finish()
W&B API는 api.runs()를 사용하여 Project 내의 여러 Runs를 쿼리하는 방법도 제공합니다. 가장 일반적인 유스 케이스는 커스텀 분석을 위해 Runs 데이터를 내보내는 것입니다. 쿼리 인터페이스는 MongoDB가 사용하는 것과 동일합니다.runs = api.runs(
"username/project",
{"$or": [{"config.experiment_name": "foo"}, {"config.experiment_name": "bar"}]},
)
print(f"Found {len(runs)} runs")
api.runs를 호출하면 이터러블하고 리스트처럼 동작하는 Runs 오브젝트가 반환됩니다. 기본적으로 이 오브젝트는 필요에 따라 한 번에 50개의 Runs를 순차적으로 로드하지만, per_page 키워드 인수를 사용하여 페이지당 로드되는 수를 변경할 수 있습니다.
api.runs는 order 키워드 인수도 허용합니다. 기본 정렬 순서는 -created_at입니다. 오름차순으로 결과를 정렬하려면 +created_at을 지정하세요. config 또는 summary 값으로 정렬할 수도 있습니다. 예를 들어, summary.val_acc 또는 config.experiment_name 등이 가능합니다.
에러 처리
W&B 서버와 통신하는 동안 오류가 발생하면 wandb.CommError가 발생합니다. 원래의 예외는 exc 속성을 통해 조사할 수 있습니다.
API를 통해 최신 git commit 가져오기
UI에서 Run을 클릭한 다음 Run 페이지의 Overview 탭을 클릭하면 최신 git commit을 볼 수 있습니다. 이는 wandb-metadata.json 파일에도 들어 있습니다. Public API를 사용하면 run.commit으로 git 해시를 가져올 수 있습니다.
Run 실행 중에 이름과 ID 가져오기
wandb.init()을 호출한 후 스크립트에서 다음과 같이 무작위 Run ID나 읽기 쉬운 Run 이름에 엑세스할 수 있습니다:
- 고유 Run ID (8자 해시):
run.id
- 무작위 Run 이름 (읽기 쉬운 형식):
run.name
Runs에 유용한 식별자를 설정하는 방법은 다음과 같습니다:
- Run ID: 생성된 해시 그대로 두는 것이 좋습니다. 이는 Project 내의 모든 Runs 사이에서 고유해야 합니다.
- Run 이름: 차트에서 서로 다른 라인을 구분할 수 있도록 짧고 읽기 쉬우며 가급적 고유한 이름을 사용하는 것이 좋습니다.
- Run 메모: Run에서 무엇을 하고 있는지에 대한 간단한 설명을 넣기에 좋습니다.
wandb.init(notes="메모 내용")으로 설정할 수 있습니다.
- Run 태그: Run 태그로 항목을 동적으로 추적하고, UI의 필터를 사용하여 원하는 Runs만 필터링하세요. 스크립트에서 태그를 설정한 후 UI의 Runs 테이블이나 Run 페이지의 Overview 탭에서 수정할 수 있습니다. 자세한 안내는 여기를 참조하세요.
Public API 예시
matplotlib 또는 seaborn 시각화를 위해 데이터 내보내기
일반적인 내보내기 패턴은 API 예시를 확인하세요. 커스텀 플롯이나 확장된 Runs 테이블에서 다운로드 버튼을 클릭하여 브라우저에서 CSV를 다운로드할 수도 있습니다.
Run에서 메트릭 읽기
이 예제는 "<entity>/<project>/<run_id>"에 저장된 Run에 대해 run.log({"accuracy": acc})로 저장된 타임스탬프와 정확도를 출력합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
if run.state == "finished":
for i, row in run.history().iterrows():
print(row["_timestamp"], row["accuracy"])
Runs 필터링
MongoDB 쿼리 언어를 사용하여 필터링할 수 있습니다.
runs = api.runs(
"<entity>/<project>",
{"$and": [{"created_at": {"$lt": "YYYY-MM-DDT##", "$gt": "YYYY-MM-DDT##"}}]},
)
Run에서 특정 메트릭 읽기
Run에서 특정 메트릭을 가져오려면 keys 인수를 사용하세요. run.history()를 사용할 때 기본 샘플 수는 500개입니다. 특정 메트릭을 포함하지 않는 로깅된 단계(steps)는 출력 데이터프레임에서 NaN으로 나타납니다. keys 인수를 사용하면 API가 나열된 메트릭 키가 포함된 단계들을 더 자주 샘플링하게 됩니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
if run.state == "finished":
for i, row in run.history(keys=["accuracy"]).iterrows():
print(row["_timestamp"], row["accuracy"])
두 Runs 비교
이 코드는 run1과 run2 사이에서 서로 다른 설정 파라미터를 출력합니다.
import pandas as pd
import wandb
api = wandb.Api()
# <entity>, <project>, <run_id>를 실제 값으로 바꾸세요
run1 = api.run("<entity>/<project>/<run_id>")
run2 = api.run("<entity>/<project>/<run_id>")
df = pd.DataFrame([run1.config, run2.config]).transpose()
df.columns = [run1.name, run2.name]
print(df[df[run1.name] != df[run2.name]])
c_10_sgd_0.025_0.01_long_switch base_adam_4_conv_2fc
batch_size 32 16
n_conv_layers 5 4
optimizer rmsprop adam
Run 종료 후 요약 메트릭 업데이트하기
이 예제는 이전 Run의 정확도를 0.9로 설정합니다. 또한 이전 Run의 정확도 히스토그램을 numpy_array의 히스토그램으로 수정합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.summary["accuracy"] = 0.9
run.summary["accuracy_histogram"] = wandb.Histogram(numpy_array)
run.summary.update()
완료된 Run에서 메트릭 이름 바꾸기
이 예제는 테이블의 요약 컬럼 이름을 바꿉니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.summary["new_name"] = run.summary["old_name"]
del run.summary["old_name"]
run.summary.update()
컬럼 이름 변경은 테이블에만 적용됩니다. 차트는 여전히 원래 이름으로 메트릭을 참조합니다.
기존 Run의 설정(config) 업데이트
이 예제는 설정 중 하나를 업데이트합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.config["key"] = updated_value
run.update()
시스템 리소스 소비량을 CSV 파일로 내보내기
아래 코드 조각은 시스템 리소스 소비량을 찾아 CSV로 저장합니다.
import wandb
with wandb.Api().run("<entity>/<project>/<run_id>") as run:
system_metrics = run.history(stream="events")
system_metrics.to_csv("sys_metrics.csv")
샘플링되지 않은 메트릭 데이터 가져오기
history에서 데이터를 가져올 때 기본적으로 500개 포인트로 샘플링됩니다. run.scan_history()를 사용하면 로깅된 모든 데이터 포인트를 가져올 수 있습니다. 다음은 history에 로깅된 모든 loss 데이터 포인트를 다운로드하는 예제입니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
history = run.scan_history()
losses = [row["loss"] for row in history]
history에서 페이지 단위로 데이터 가져오기
백엔드에서 메트릭을 가져오는 속도가 느리거나 API 요청이 타임아웃되는 경우, 개별 요청이 만료되지 않도록 scan_history의 페이지 크기를 낮춰볼 수 있습니다. 기본 페이지 크기는 500이며, 가장 잘 작동하는 크기를 찾기 위해 실험해 볼 수 있습니다:
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.scan_history(keys=sorted(cols), page_size=100)
Project의 모든 Runs에서 메트릭을 CSV 파일로 내보내기
이 스크립트는 Project 내의 Runs를 가져와 이름, 설정, 요약 통계를 포함하는 데이터프레임과 CSV를 생성합니다. <entity>와 <project>를 실제 값으로 바꾸세요.
import pandas as pd
import wandb
api = wandb.Api()
entity, project = "<entity>", "<project>"
runs = api.runs(entity + "/" + project)
summary_list, config_list, name_list = [], [], []
for run in runs:
# .summary에는 정확도와 같은 메트릭의
# 출력 키/값이 포함됩니다.
# 대용량 파일을 제외하기 위해 ._json_dict를 호출합니다.
summary_list.append(run.summary._json_dict)
# .config에는 하이퍼파라미터가 포함됩니다.
# _로 시작하는 특수 값을 제거합니다.
config_list.append({k: v for k, v in run.config.items() if not k.startswith("_")})
# .name은 Run의 읽기 쉬운 이름입니다.
name_list.append(run.name)
runs_df = pd.DataFrame(
{"summary": summary_list, "config": config_list, "name": name_list}
)
runs_df.to_csv("project.csv")
Run 시작 시간 가져오기
이 코드 조각은 Run이 생성된 시간을 가져옵니다.
import wandb
api = wandb.Api()
run = api.run("entity/project/run_id")
start_time = run.created_at
완료된 Run에 파일 업로드하기
아래 코드 조각은 선택한 파일을 완료된 Run에 업로드합니다.
import wandb
api = wandb.Api()
run = api.run("entity/project/run_id")
run.upload_file("file_name.extension")
Run에서 파일 다운로드하기
cifar Project에서 Run ID uxte44z7과 연관된 “model-best.h5” 파일을 찾아 로컬에 저장합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.file("model-best.h5").download()
Run의 모든 파일 다운로드하기
Run과 연관된 모든 파일을 찾아 로컬에 저장합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
for file in run.files():
file.download()
특정 Sweep에서 Runs 가져오기
이 코드 조각은 특정 Sweep과 연관된 모든 Runs를 다운로드합니다.
import wandb
api = wandb.Api()
sweep = api.sweep("<entity>/<project>/<sweep_id>")
sweep_runs = sweep.runs
Sweep에서 최적의 Run 가져오기
다음 코드 조각은 지정된 Sweep에서 최적의 Run을 가져옵니다.
import wandb
api = wandb.Api()
sweep = api.sweep("<entity>/<project>/<sweep_id>")
best_run = sweep.best_run()
best_run은 Sweep 설정의 metric 파라미터에 정의된 최적의 메트릭을 가진 Run입니다.
Sweep에서 최적의 모델 파일 다운로드하기
이 코드 조각은 모델 파일을 model.h5로 저장한 Sweep의 Runs 중에서 검증 정확도가 가장 높은 모델 파일을 다운로드합니다.
import wandb
api = wandb.Api()
sweep = api.sweep("<entity>/<project>/<sweep_id>")
runs = sorted(sweep.runs, key=lambda run: run.summary.get("val_acc", 0), reverse=True)
val_acc = runs[0].summary.get("val_acc", 0)
print(f"Best run {runs[0].name} with {val_acc}% val accuracy")
runs[0].file("model.h5").download(replace=True)
print("Best model saved to model-best.h5")
Run에서 특정 확장자를 가진 모든 파일 삭제하기
이 코드 조각은 Run에서 특정 확장자를 가진 파일들을 삭제합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
extension = ".png"
files = run.files()
for file in files:
if file.name.endswith(extension):
file.delete()
시스템 메트릭 데이터 다운로드
이 코드 조각은 Run의 모든 시스템 리소스 소비 메트릭을 데이터프레임으로 생성하고 CSV로 저장합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
system_metrics = run.history(stream="events")
system_metrics.to_csv("sys_metrics.csv")
요약 메트릭 업데이트
사전(dictionary)을 전달하여 요약 메트릭을 업데이트할 수 있습니다.
summary.update({"key": val})
Run을 실행한 코맨드 가져오기
각 Run은 Run Overview 페이지에 이를 실행한 코맨드를 캡처합니다. API에서 이 코맨드를 가져오려면 다음과 같이 실행할 수 있습니다:
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
meta = json.load(run.file("wandb-metadata.json").download())
program = ["python"] + [meta["program"]] + meta["args"]
