Lược đồ lưu trữ và truy vấn trực tiếp

Trackio lưu trữ mỗi dự án trong một cơ sở dữ liệu SQLite riêng và có thể xuất dữ liệu đó sang parquet để đồng bộ hóa, Spaces tĩnh và phân tích trực tiếp. Trang này tài liệu hóa lược đồ SQLite trực tiếp, bố cục parquet dẫn xuất và lệnh trackio query mới để chạy SQL chỉ đọc.

Dữ liệu được lưu ở đâu

• Cơ sở dữ liệu dự án cục bộ nằm trong TRACKIO_DIR, mặc định là ~/.cache/huggingface/trackio.
• Mỗi dự án được lưu trữ dưới dạng một tệp SQLite riêng biệt: {project}.db.
• Phương tiện và tệp đã tải lên nằm dưới TRACKIO_DIR/media/.
• Mỗi trace còn được ghi dưới dạng tệp phiên agent có thể hiển thị trên Hub tại TRACKIO_DIR/traces/ (trên Space, là tiền tố traces/ của bucket). Đây là sản phẩm hiển thị cho trình xem trace agent của Hub; bảng traces vẫn là nguồn chính. Xem Traces.
• Khi đồng bộ hóa lên Hugging Face, Trackio xuất các tệp parquet từ cơ sở dữ liệu SQLite trước khi tải lên.

Truy vấn Dữ Liệu Trực Tiếp

Sử dụng CLI khi bạn cần một truy vấn tổng quát mà trackio list hoặc trackio get chưa bao phủ:

trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name ORDER BY last_step DESC"

Thêm --json để có đầu ra có thể đọc được bằng máy:

trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name" --json

Cùng một lệnh này hoạt động với một Space từ xa:

trackio query project --project "my-project" --sql "SELECT COUNT(*) AS num_alerts FROM alerts" --space username/my-space --json

trackio query chỉ chấp nhận các truy vấn SELECT, WITH và PRAGMA schema an toàn, bao gồm việc đọc PRAGMA user_version.

Sơ đồ SQLite

Sơ đồ trực tiếp được định nghĩa trong trackio/sqlite_storage.py bởi SQLiteStorage.init_db().

metrics

Chỉ mục:

• idx_metrics_run_step trên (run_name, step)
• idx_metrics_run_timestamp trên (run_name, timestamp)
• idx_metrics_log_id là chỉ mục một phần duy nhất trên log_id
• Chỉ mục một phần idx_metrics_pending trên space_id

configs

Chỉ mục và ràng buộc:

• UNIQUE(run_name)
• idx_configs_run_name trên (run_name)

system_metrics

Chỉ mục:

• idx_system_metrics_run_timestamp trên (run_name, timestamp)
• idx_system_metrics_log_id là chỉ mục một phần duy nhất trên log_id
• Chỉ mục một phần idx_system_metrics_pending trên space_id

traces

Chỉ mục:

• idx_traces_run_step trên (run_id, step)
• idx_traces_run_timestamp trên (run_id, timestamp)
• idx_traces_search trên search_text

project_metadata

pending_uploads

cảnh báo

Chỉ mục:

• idx_alerts_run trên (run_name)
• idx_alerts_timestamp trên (timestamp)
• idx_alerts_alert_id là chỉ mục một phần duy nhất trên alert_id

artifacts

Chỉ mục và ràng buộc:

• UNIQUE(name)

artifact_versions

Chỉ mục và ràng buộc:

• UNIQUE(artifact_id, version)
• UNIQUE(artifact_id, manifest_digest)

artifact_aliases

Chỉ mục và ràng buộc:

• PRIMARY KEY (artifact_id, alias)

run_artifact_links

Chỉ mục và ràng buộc:

• CHECK(direction IN ('input', 'output'))
• idx_run_artifact_links_run trên (run_id, run_name)
• idx_run_artifact_links_version trên (artifact_version_id)
• idx_run_artifact_links_unique chỉ mục duy nhất trên (run_id, artifact_version_id, direction)

Bảng đăng ký

Registry databases — các dự án có tên registry-<name>, được tạo bởi Api.create_registry — chứa các bảng chuẩn ở trên cùng với bốn bảng bên dưới, được định nghĩa trong trackio/registry_storage.py bởi RegistryStorage.init_registry_db(). Số phiên bản của collection đến từ collections.next_version, chỉ tăng lên: một phiên bản collection không bao giờ được sử dụng lại, kể cả sau khi unlink. Mọi thao tác thay đổi registry cũng thêm một dòng vào registry_events trong cùng một giao dịch.

collections

collection_links

Ràng buộc:

• UNIQUE(collection_id, source_project, source_artifact, source_version) — một phiên bản nguồn chỉ được liên kết tối đa một lần cho mỗi bộ sưu tập
• UNIQUE(collection_id, collection_version)

collection_aliases

Ràng buộc:

• PRIMARY KEY (collection_id, alias) — một phiên bản cho mỗi alias trong mỗi collection

registry_events

Log là dạng thức chính thức của một registry: các bảng ở trên là một phép gập (fold) của nó. Một registry dựa trên bucket lưu trữ các sự kiện giống nhau dưới dạng mỗi sự kiện là một đối tượng (xem hướng dẫn về Registry) và vật chất hóa các bảng này cục bộ.

Cách các khối dữ liệu chỉ số được lưu trữ

• Các chỉ số người dùng được lưu trữ dưới dạng văn bản JSON trong metrics.metrics.
• Các chỉ số hệ thống được lưu trữ dưới dạng văn bản JSON trong system_metrics.metrics.
• Cấu hình chạy được lưu dưới dạng văn bản JSON trong configs.config.
• Các API cấp cao hơn của Trackio sẽ khử chuỗi hóa các khối JSON này trước khi trả về chúng.

Mẫu truy vấn trực tiếp phổ biến:

trackio query project --project "my-project" --sql "SELECT timestamp, step, metrics FROM metrics WHERE run_name = 'run-1' ORDER BY step DESC LIMIT 5"

Ví dụ kiểm tra schema:

trackio query project --project "my-project" --sql "PRAGMA table_info(metrics)"

Bố cục Parquet

Trackio tạo ra các tệp parquet từ SQLite bằng cách làm phẳng các cột JSON thành các cột thông thường.

Xuất parquet cục bộ

SQLiteStorage.export_to_parquet() ghi:

• {project}.parquet từ metrics
• {project}_system.parquet từ system_metrics
• {project}_configs.parquet từ configs
• {project}_traces.parquet từ traces
• {project}_{table}.parquet cho mỗi bảng artifact (artifacts, artifact_versions, artifact_aliases, run_artifact_links)

Các tệp parquet đã được làm phẳng giữ lại các cột cấu trúc như timestamp, run_name và step, sau đó thêm một cột cho mỗi khóa được tìm thấy trong payload JSON.

Static Space và xuất dataset

SQLiteStorage.export_for_static_space() ghi:

• metrics.parquet
• aux/system_metrics.parquet
• aux/configs.parquet
• aux/traces.parquet
• aux/artifacts.parquet, aux/artifact_versions.parquet, aux/artifact_aliases.parquet, và aux/run_artifact_links.parquet
• runs.json
• settings.json

Triển khai tĩnh sao chép các tệp phương tiện vào media/ và các blob sản phẩm vào artifacts/blobs/sha256/{prefix}/{digest} cùng với các bản xuất này, nhờ đó bảng điều khiển chỉ chạy trên trình duyệt có thể phục vụ các lượt tải sản phẩm trực tiếp từ bộ dữ liệu hoặc bucket.

Đây là bố cục được sử dụng cho các Spaces tĩnh và các bộ dữ liệu đã xuất.

Các ví dụ truy vấn hữu ích

Danh sách bảng:

trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name"

Tìm bước mới nhất cho mỗi lần chạy:

trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name ORDER BY last_step DESC"

Kiểm tra các cảnh báo gần đây:

trackio query project --project "my-project" --sql "SELECT timestamp, run_name, level, title, step FROM alerts ORDER BY timestamp DESC LIMIT 20"

Kiểm tra các cấu hình đã lưu:

trackio query project --project "my-project" --sql "SELECT run_name, created_at, config FROM configs ORDER BY created_at DESC"

Phiên bản Schema và Di trú

Mỗi cơ sở dữ liệu dự án ghi lại phiên bản schema của nó trong PRAGMA user_version:

trackio query project --project "my-project" --sql "PRAGMA user_version"

SQLiteStorage.init_db() nâng cấp cơ sở dữ liệu lên SCHEMA_VERSION (được định nghĩa trong trackio/sqlite_storage.py) mỗi khi nó được mở để ghi, và một máy chủ Trackio sẽ di chuyển (migrate) mọi cơ sở dữ liệu dự án khi nó khởi động. Các cơ sở dữ liệu được ghi trước khi có cơ chế phân phiên bản sẽ báo phiên bản 0 và được nâng lên phiên bản 1 bằng các câu lệnh CREATE TABLE IF NOT EXISTS và ALTER TABLE ... ADD COLUMN mang tính bổ sung trong init_db(). Phiên bản 2 cấp cho các cơ sở dữ liệu được ghi trước Trackio 0.24 một run_id trên mọi bảng có phạm vi theo run: các phiên bản đó chỉ xác định một run bằng tên của nó, do đó mỗi tên run sẽ trở thành một run với một id mới.

Để thay đổi schema hoặc viết lại dữ liệu hiện có theo cách mà các câu lệnh đó không thể diễn đạt, hãy thêm một bước vào _SCHEMA_MIGRATIONS và tăng SCHEMA_VERSION:

def _split_loss_column(cursor):
    cursor.execute("ALTER TABLE metrics ADD COLUMN loss REAL")
    cursor.execute("UPDATE metrics SET loss = json_extract(metrics, '$.loss')")


SCHEMA_VERSION = 3
_SCHEMA_MIGRATIONS = {2: _migrate_add_run_ids, 3: _split_loss_column}

_SCHEMA_MIGRATIONS[n] nâng cấp cơ sở dữ liệu từ phiên bản n - 1 lên n. Mỗi bước được thực thi trong một savepoint riêng cùng với việc tăng phiên bản, do đó nếu một bước thất bại, cơ sở dữ liệu sẽ được giữ ở phiên bản cuối cùng đã hoàn tất. Cơ sở dữ liệu có phiên bản mới hơn so với phiên bản mà Trackio đang chạy sẽ không bị thay đổi.

trackio bump dựa vào điều này: sau khi khởi động lại một Space trên phiên bản Trackio cục bộ, nó kiểm tra rằng mọi cơ sở dữ liệu dự án đều báo cáo SCHEMA_VERSION cục bộ. Bài kiểm tra e2e trong tests/e2e-spaces/test_space_bump.py chạy mọi migration trên dữ liệu được ghi bởi Trackio 0.21.0 và 0.37.1.

Ghi chú về tính ổn định

Trackio vẫn đang ở giai đoạn beta. Schema được tài liệu hóa tại đây để con người và các agent có thể truy vấn trực tiếp, nhưng các bản phát hành trong tương lai có thể thay đổi schema và yêu cầu chạy migration hoặc tạo lại cơ sở dữ liệu cục bộ.