Trackio documentation
Theo dõi
Theo dõi
Giới thiệu
Trackio giúp bạn tổ chức các thí nghiệm của mình trong một dự án. Một dự án là tập hợp các lần chạy, trong đó mỗi lần chạy đại diện cho một lần thực thi mã của bạn với một bộ tham số và kết quả cụ thể.
Khởi tạo
Để bắt đầu theo dõi một thí nghiệm với Trackio, trước tiên bạn cần khởi tạo một dự án bằng hàm init():
import trackio
trackio.init(project="my_project")- Nếu dự án đã tồn tại, nó sẽ được tải.
- Nếu không, Trackio sẽ tạo một cái mới.
Trong cả hai trường hợp, một lượt chạy mới sẽ được khởi động tự động, sẵn sàng để bạn ghi lại dữ liệu.
Đặt tên cho lần chạy
Việc đặt tên có ý nghĩa cho mỗi lần chạy là một ý tưởng hay để dễ dàng tổ chức và tham chiếu sau này.
Bạn có thể đặt tên bằng cách sử dụng tham số name:
trackio.init(project="my_project", name="my_first_run")Nếu không cung cấp tên, Trackio sẽ tạo ra một tên mặc định.
Nhóm các lần chạy
Bạn có thể tổ chức các lần chạy liên quan thành các nhóm bằng tham số group. Điều này đặc biệt hữu ích khi bạn chạy nhiều thí nghiệm với các cấu hình khác nhau nhưng muốn so sánh chúng cùng nhau:
# Group runs by experiment type
trackio.init(project="my_project", name="baseline_run_1", group="baseline")
trackio.init(project="my_project", name="augmented_run_1", group="augmented")
trackio.init(project="my_project", name="tuned_run_1", group="tuned")Các lần chạy có cùng tên nhóm có thể được nhóm lại trong thanh bên, giúp dễ dàng so sánh các thí nghiệm liên quan. Bạn cũng có thể nhóm các lần chạy theo bất kỳ tham số cấu hình nào khác (xem Tracking Configuration bên dưới).
Ghi log từ xa (Hugging Face Space hoặc máy chủ tự lưu trữ)
Mặc định, các chỉ số được lưu cục bộ và bạn mở bảng điều khiển trên máy của mình. Thay vào đó, bạn có thể gửi các chỉ số đến:
- Một Hugging Face Space, bằng cách truyền
space_id(hoặc đặtTRACKIO_SPACE_ID). Trackio có thể tạo hoặc tái sử dụng Space và đồng bộ hóa dữ liệu tại đó. - Một server Trackio tự lưu trữ (HTTP hoặc HTTPS), bằng cách truyền
server_url(hoặc đặtTRACKIO_SERVER_URL). Sử dụng URL truy cập ghi từtrackio.show()(tùy chọn kèmwrite_tokentrong query), hoặc một URL cơ bản cùngTRACKIO_WRITE_TOKEN. Client xác thực bằng cùng token ghi mà dashboard sử dụng (không phải token Hugging Face của bạn).
Nếu cả Space và URL tự lưu trữ đều được cấu hình (space_id / TRACKIO_SPACE_ID cùng với server_url / TRACKIO_SERVER_URL), Space sẽ được ưu tiên và URL tự lưu trữ sẽ bị bỏ qua. Các tùy chọn như dataset_id (đã ngừng hỗ trợ; hãy dùng bucket_id thay thế) và bucket_id áp dụng cho các triển khai trên Hugging Face; khi chỉ có server_url đang có hiệu lực, hãy cấu hình lưu trữ trên máy chủ chạy server (xem Biến môi trường).
Để biết các bước cài đặt (chạy trackio show, liên kết với 0.0.0.0, ghi token), hãy xem Tự lưu trữ Server.
Bảng điều khiển tích hợp sẽ kiểm tra các lần chạy và chỉ số mới mỗi 1 giây trên localhost và mỗi 2 giây khi được mở trên một Hugging Face Space (*.hf.space), nhằm giảm bớt giới hạn tần suất trên URL của Space.
Ghi log dữ liệu
Khi run của bạn đã được khởi tạo, bạn có thể bắt đầu ghi log dữ liệu bằng hàm log():
trackio.log({"loss": 0.05})Trackio được viết theo cách phòng thủ để các sự cố phía Trackio không bao giờ làm gián đoạn mã thực nghiệm chính của bạn. Trong quá trình sử dụng bình thường, các vấn đề trong các luồng ghi log, flush hoặc giao dịch của Trackio sẽ bị giảm xuống thành các cảnh báo và đệm cục bộ thay vì các ngoại lệ từ vòng lặp huấn luyện của bạn.
Mọi lần gọi log() đều tự động tăng bộ đếm bước. Nếu bạn muốn ghi log nhiều chỉ số cùng lúc, hãy truyền chúng cùng nhau:
trackio.log({
"loss": 0.05,
"accuracy": 0.95,
})Bảng ghi log
Bạn có thể ghi log dữ liệu bảng bằng lớp Table. Điều này hữu ích để theo dõi các kết quả như dự đoán, hoặc bất kỳ dữ liệu có cấu trúc nào. Bảng có thể bao gồm các cột hình ảnh bằng cách sử dụng lớp Image.
import pandas as pd
df = pd.DataFrame(
{
"prompt": ["Trackio", "Logging is"],
"completion": ["is great!", "easy and fun!"],
"reward": [0.123, 0.456],
}
)
trackio.log(
{
...
"texts": trackio.Table(dataframe=df),
}
)Báo cáo ghi log (Markdown)
Bạn có thể ghi log các báo cáo markdown bằng lớp Markdown. Các báo cáo được hiển thị trên trang Reports trong dashboard, trong đó báo cáo mới nhất xuất hiện đầu tiên.
trackio.log(
{
"training_report": trackio.Markdown(
"""# Training Report
Final validation accuracy: **0.92**
- Best epoch: 18
- Early stopping: enabled
"""
)
}
)Bạn có thể ghi log báo cáo nhiều lần trong một lần chạy (ví dụ: một báo cáo cho mỗi checkpoint), và Trackio sẽ giữ lại toàn bộ lịch sử qua các bước.
Để xem một script hoàn chỉnh có thể chạy được, hãy xem examples/training-with-report.py.
Ghi log hình ảnh
Bạn có thể ghi log hình ảnh bằng lớp Image.
trackio.log({"image": trackio.Image(value="path/to/image.png", caption="Image caption")})Hình ảnh có thể được ghi log từ một đường dẫn, một mảng numpy, hoặc một hình ảnh PIL.
Ghi log video
Bạn có thể ghi log video bằng lớp Video.
import trackio
import numpy as np
# Create a simple video from numpy array
frames = np.random.randint(0, 255, (10, 3, 64, 64), dtype=np.uint8)
video = trackio.Video(frames, caption="Random video", fps=30)
trackio.log({"my_video": video})
# Create a batch of videos
batch_frames = np.random.randint(0, 255, (3, 10, 3, 64, 64), dtype=np.uint8)
batch_video = trackio.Video(batch_frames, caption="Batch of videos", fps=15)
trackio.log({"batch_videos": batch_video})
# Create video from file path
video = trackio.Video("path/to/video.mp4", caption="Video from file")
trackio.log({"file_video": video})Video có thể được ghi log từ đường dẫn tệp hoặc một mảng numpy.
Yêu cầu đối với mảng Numpy:
- Phải có kiểu
np.uint8với các giá trị RGB trong khoảng[0, 255] - Shape phải là một trong các dạng sau:
(frames, channels, height, width)cho một video đơn(batch, frames, channels, height, width)cho nhiều video (sẽ được xếp thành lưới)
Ghi log âm thanh
Bạn có thể ghi log âm thanh bằng lớp Audio.
import trackio
import numpy as np
# Generate a 1-second 440 Hz sine wave (mono)
sr = 16000
t = np.linspace(0, 1, sr, endpoint=False)
wave = 0.2 * np.sin(2 * np.pi * 440 * t)
audio = trackio.Audio(wave, caption="A4 sine", sample_rate=sr, format="wav")
trackio.log({"tone": audio})
# Stereo from numpy array (shape: samples, 2)
stereo = np.stack([wave, wave], axis=1)
audio = trackio.Audio(stereo, caption="Stereo", sample_rate=sr, format="mp3")
trackio.log({"stereo": audio})
# From an existing file
audio = trackio.Audio("path/to/audio.wav", caption="From file")
trackio.log({"file_audio": audio})Audio có thể được ghi log từ một đường dẫn tệp hoặc một mảng numpy.
Yêu cầu đối với mảng Numpy:
- Shape phải là
(samples,)cho mono hoặc(samples, 2)cho stereo sample_ratephải được cung cấp khi ghi log từ mảng numpy- Giá trị có thể là float hoặc integer; các giá trị float được chuẩn hóa theo đỉnh và chuyển đổi sang PCM 16-bit
formatcó thể là"wav"hoặc"mp3"khi ghi log từ một mảng numpy (mặc định là"wav")
Ghi log các đối tượng 3D
Sử dụng Object3D với cùng API trackio.log() như các phương tiện khác:
import numpy as np
import trackio
trackio.log({"scene": trackio.Object3D("path/to/scene.glb", caption="Prediction")})
points = np.random.normal(size=(50_000, 3))
trackio.log({"point_cloud": trackio.Object3D.from_numpy(points)})| Định dạng | Mesh | Đám mây điểm | Gaussian splat |
|---|---|---|---|
.glb / .gltf | Có | Thông qua glTF | Không |
.obj | Có | Không | Không |
.stl | Có | Không | Không |
.ply | Có | Có | Có |
.splat | Không | Không | Có |
Mảng NumPy phải có một trong các hình dạng sau:
(N, 3)cho tọa độ XYZ.(N, 4)cho XYZ cùng một danh mục nguyên từ 1 đến 14. Trackio áp dụng bảng màu danh mục tất định.(N, 6)cho các giá trị XYZ và RGB nguyên từ 0 đến 255.
Tọa độ phải hữu hạn. Các đám mây điểm thông thường bị giới hạn xác định ở 300.000 điểm được render; số lượng điểm gốc và số điểm được render vẫn hiển thị. Trackio không giảm mật độ lưới (mesh) hay Gaussian splats.
Mô hình phải tự chứa. Dữ liệu glTF nhúng dạng URI được hỗ trợ, nhưng các tài nguyên glTF bên ngoài, thư viện vật liệu OBJ và kết cấu PLY thì không. Mọi đối tượng đều sử dụng bố cục <project>/<run>/<step>/<uuid>.<ext> giống như hình ảnh, video và âm thanh.
Các đối tượng 3D cũng hoạt động trong bảng:
table = trackio.Table(
columns=["sample", "reconstruction"],
data=[["chair", trackio.Object3D("chair.gltf")]],
)
trackio.log({"reconstructions": table})Ghi log HTML và hình ảnh
Bạn có thể ghi log HTML bằng lớp Html.
trackio.log({"report": trackio.Html("<h1>Results</h1>")})Biểu đồ Matplotlib và Plotly được chuyển đổi sang HTML:
import plotly.express as px
fig = px.line(x=[1, 2, 3], y=[4, 5, 6])
trackio.log({"plot": fig})Ghi log các chỉ số hệ thống
Trackio có thể tự động ghi lại các chỉ số hệ thống trong nền. Nó hỗ trợ cả GPU NVIDIA và các máy Mac Apple Silicon (dòng M).
Cài đặt:
# NVIDIA GPU monitoring
pip install trackio[gpu]
# Apple Silicon system monitoring
pip install trackio[apple-gpu]Ghi log tự động (mặc định):
Khi gói phù hợp được cài đặt và phần cứng tương thích được phát hiện, các chỉ số hệ thống sẽ được ghi log tự động ở chế độ nền (mặc định là mỗi 10 giây):
import trackio
# Auto-enabled when hardware is detected
trackio.init(project="my_project")
for step in range(100):
# ... training code ...
trackio.log({"loss": loss})
# System metrics are logged automatically in the background
trackio.finish()Bạn có thể tùy chỉnh khoảng thời gian hoặc tắt tính năng ghi log tự động:
# Custom interval
trackio.init(project="my_project", gpu_log_interval=5.0)
# Disable auto-logging
trackio.init(project="my_project", auto_log_gpu=False)Ghi log thủ công:
Bạn cũng có thể ghi lại các chỉ số hệ thống thủ công vào những thời điểm cụ thể bằng cách sử dụng log_gpu():
import trackio
trackio.init(project="my_project", auto_log_gpu=False)
for step in range(100):
# ... training code ...
trackio.log({"loss": loss})
trackio.log_gpu() # Log system metrics at current time
trackio.finish()Chỉ số GPU NVIDIA:
Chỉ số theo từng GPU (gpu/{i}/{metric}):
gpu/0/utilization- Tỷ lệ sử dụng GPU %gpu/0/memory_utilization- Tỉ lệ sử dụng bộ điều khiển bộ nhớgpu/0/allocated_memory- Bộ nhớ đã cấp phát tính bằng GiBgpu/0/total_memory- Tổng bộ nhớ tính bằng GiBgpu/0/memory_usage- Tỷ lệ sử dụng bộ nhớ (0-1)gpu/0/temp- Nhiệt độ tính bằng độ Cgpu/0/power- Công suất tiêu thụ tính bằng wattgpu/0/power_percent- Công suất tính theo % giới hạngpu/0/power_limit- Giới hạn công suất tính bằng wattgpu/0/sm_clock- Tốc độ xung nhịp SM tính bằng MHzgpu/0/memory_clock- Tốc độ xung nhịp bộ nhớ tính bằng MHzgpu/0/fan_speed- Tốc độ quạt %gpu/0/performance_state- Trạng thái hiệu năng (P0-P15)gpu/0/energy_consumed- Năng lượng tiêu thụ kể từ khi bắt đầu chạy, tính bằng Joulesgpu/0/pcie_tx- Băng thông truyền PCIe (MB/s)gpu/0/pcie_rx- Băng thông nhận PCIe tính bằng MB/sgpu/0/throttle_thermal- Throttling nhiệt (0/1)gpu/0/throttle_power- Throttling công suất (0/1)gpu/0/throttle_hw_slowdown- Giảm tốc phần cứng (0/1)gpu/0/throttle_apps- Throttling xung nhịp ứng dụng (0/1)gpu/0/corrected_memory_errors- Lỗi bộ nhớ đã được ECC sửagpu/0/uncorrected_memory_errors- Lỗi ECC không thể sửa
Các chỉ số tổng hợp:
gpu/mean_utilization- Mức sử dụng GPU trung bình trên tất cả các GPUgpu/total_allocated_memory- Tổng bộ nhớ đã sử dụng trên tất cả các GPU, tính bằng GiBgpu/total_power- Tổng công suất tiêu thụ trên tất cả các GPUgpu/max_temp- Nhiệt độ tối đa trên tất cả các GPU
Chỉ số Apple Silicon:
cpu/utilization- Tỷ lệ sử dụng CPU tổng thể %cpu/{i}/utilization- Tỉ lệ sử dụng CPU theo từng nhân %cpu/frequency- Tần số CPU hiện tại tính bằng MHzcpu/frequency_max- Tần số CPU tối đa tính bằng MHzmemory/used- Bộ nhớ đã sử dụng (GiB)memory/total- Tổng bộ nhớ tính bằng GiBmemory/available- Bộ nhớ khả dụng tính bằng GiBmemory/percent- Tỷ lệ sử dụng bộ nhớswap/used- Swap đã sử dụng (GiB)swap/total- Tổng dung lượng swap tính bằng GiBswap/percent- Tỷ lệ sử dụng Swaptemp/{label}- Giá trị cảm biến nhiệt độ tính bằng độ C (nếu có)gpu/detected- Xác định xem có phát hiện GPU Apple hay không (0/1)
Thu thập đầu ra của console và lệnh khởi chạy
Trackio ghi lại lệnh được sử dụng để khởi chạy mỗi run (ví dụ python train.py --lr 1e-3) và hiển thị nó ở đầu trang của run trong dashboard, kèm theo một nút để sao chép. Giá trị của các đối số có tên trông giống như bí mật (chẳng hạn như --hub_token, --api-key, hoặc password=...) sẽ được thay thế bằng REDACTED. Lệnh được lưu trong cấu hình của run dưới khóa dự phòng _Command.
Trackio cũng có thể ghi lại mọi thứ mà script của bạn viết ra stdout và stderr, bao gồm các lệnh gọi print(), đầu ra của logging và tracebacks, để bạn có thể theo dõi nhật ký của một lần chạy từ dashboard khi không ở gần terminal. Việc ghi lại console bị tắt theo mặc định. Bật nó bằng cách đặt capture_console=True:
import logging
import trackio
logging.basicConfig(level=logging.INFO)
trackio.init(project="my_project", capture_console=True)
for step in range(100):
loss = ...
logging.info("step %d loss=%.4f", step, loss)
trackio.log({"loss": loss})
trackio.finish()Hoặc bật tính năng này mà không cần thay đổi mã của bạn bằng cách đặt biến môi trường TRACKIO_CAPTURE_CONSOLE:
TRACKIO_CAPTURE_CONSOLE=1 python train.py
Đầu ra được ghi lại sẽ hiển thị trong phần Console output của trang chạy (mở một lần chạy từ trang Runs). Phần này được làm mới mỗi 10 giây trong khi lần chạy đang diễn ra, và nút Download sẽ lưu toàn bộ nhật ký dưới dạng tệp văn bản. Mỗi dòng được lưu kèm theo thời gian UTC tại thời điểm nó được ghi; bảng điều khiển hiển thị thời gian đó theo múi giờ địa phương của bạn. Đầu ra được lưu mỗi 10 giây và khi lần chạy kết thúc, hoạt động cho cả các lần chạy cục bộ lẫn các lần chạy được ghi nhật ký lên một Space hoặc một máy chủ tự lưu trữ, và bị giới hạn ở mức 20 MB cho mỗi lần chạy.
Nếu tiến trình bị dừng bằng SIGTERM (giới hạn thời gian Slurm, docker stop, hoặc việc trục xuất của Kubernetes), dữ liệu đầu ra được ghi kể từ lần lưu cuối cùng sẽ bị mất. Đặt TRACKIO_HANDLE_SIGTERM=1 để lưu dữ liệu trước khi tiến trình thoát.
Console capture hoạt động bằng cách bọc phương thức write của sys.stdout và sys.stderr, do đó nó cũng thu thập các logging handlers được cấu hình trước khi trackio.init() được gọi. Đầu ra được ghi trực tiếp vào các file descriptor cơ bản, chẳng hạn như thông báo từ các C extensions hoặc subprocesses, sẽ không được thu thập.
Lưu ý: Nếu bạn ghi log vào một Space công khai, đầu ra console được ghi lại sẽ hiển thị cho bất kỳ ai có thể xem bảng điều khiển. Hãy đảm bảo script của bạn không in các thông tin bí mật trước khi bật tính năng ghi lại console.
Hoàn tất một Run
Khi run của bạn hoàn tất, hãy hoàn tất nó bằng finish(). Điều này đánh dấu run là đã hoàn thành và lưu tất cả dữ liệu đã được ghi log:
trackio.finish()
Tiếp tục một Run
Trackio nhận diện các run bên trong bằng một run_id ổn định. name thân thiện với người dùng không còn bắt buộc phải duy nhất, vì vậy bạn có thể tạo nhiều run với cùng một tên hiển thị.
Nếu bạn cần tiếp tục lần chạy gần nhất với một tên đã cho (ví dụ, sau một sự gián đoạn), hãy gọi init() một lần nữa với cùng tên dự án và tên chạy, và đặt resume="must":
trackio.init(project="my_project", name="my_first_run", resume="must")Điều này sẽ tải run được tạo gần nhất có tên đó để bạn có thể tiếp tục ghi log dữ liệu bằng cùng một run_id. Nhưng nếu bạn đặt resume="must" và không có run trước đó nào có cùng tên, Trackio sẽ ném ra một lỗi.
Để có nhiều linh hoạt hơn, hãy sử dụng resume="allow". Thao tác này sẽ tiếp tục chạy lần chạy gần nhất có tên đó nếu có, hoặc tạo một lần chạy mới nếu không.
Mặc định là resume="never", luôn tạo một lượt chạy mới với run_id mới, ngay cả khi đã có một lượt chạy khác cùng name.
Theo dõi Cấu hình
Bạn cũng có thể theo dõi các tham số cấu hình cho các lần chạy của mình. Điều này hữu ích để theo dõi các siêu tham số hoặc các cài đặt khác được sử dụng trong các thí nghiệm của bạn. Bạn có thể ghi lại dữ liệu cấu hình bằng cách sử dụng tham số config trong hàm init():
for batch_size in [16, 32, 64]:
for lr in [0.001, 0.01, 0.1]:
trackio.init(
project="hyperparameter_tuning",
name=f"lr_{lr}_batch_{batch_size}_run",
config={
"learning_rate": lr,
"batch_size": batch_size,
}
)
# ... your training code ...
trackio.finish()Trong bảng điều khiển, bạn có thể nhóm theo “learning_rate” hoặc “batch_size” để dễ dàng so sánh các lần chạy với các siêu tham số khác nhau.
Update on GitHub