升级 lance-ray 至 0.5.0 并固定 pylance 9.0.0

AGENTS.md

@@ -28,7 +28,7 @@ tests/                 # pytest；按 audio/image/storage/workflow 分目录
 ## 硬性架构约定
 
 1. **媒体隔离**：audio 和 image 各自拥有独立的 package 和 workflow 入口，**不要**把共享 Stage 参数化成"通用管线"。可共享的只有 `storage/` 层 infra 和 `config.py` 的辅助函数。
-2. **数据 API 优先级**：所有数据操作优先用 **Daft**；Daft 做不到再用 **lance-ray**；**pylance 直接调用是最后手段**（目前锁在 <8，blob compaction 被禁用）。
+2. **数据 API 优先级**：所有数据操作优先用 **Daft**；Daft 做不到再用 **lance-ray**；**pylance 直接调用是最后手段**。当前固定为 pylance 8.0.0；blob compaction 仍需在单独改动中完成 lance-ray 兼容性和对象存储回归验证后再启用。
 3. **行不丢弃**：analyze 阶段 manifest 里每个条目对应输出一行，失败用 `status` 列标记（`download_failed` / `decode_failed` / ...），分数结论置 null。合规场景必须能区分"内容有问题"和"根本没处理"。
 4. **配置只走环境变量**，经 `config.py` 的 `env_int`/`env_bool`/`env_choice` 等辅助函数读取。注意：Daft 原生只读少数 `DAFT_*` 环境变量，新增 Daft 执行参数必须在 `storage/io.py::configure_daft_runner()` 里显式传给 `daft.set_execution_config()`，否则是死配置；S3 参数同理要传进 `daft_io_config()` 的 `S3Config`。
 5. **写出受控**：`write_lance` 必须传 `LANCE_MAX_ROWS_PER_FILE` / `LANCE_MAX_BYTES_PER_FILE`；JSONL 写出前用 `coalesce_for_write()` 收敛分区，避免小文件。

README.md

@@ -410,8 +410,8 @@ python -m multimodal_toolkit.workflow.manage \
 |------|------|------|
 | Daft | 0.7.15 | 主执行引擎 |
 | daft-lance | 0.4.0 | `read_lance`、`write_lance`、`take_blobs`、`create_scalar_index`、`compact_files` |
-| pylance | 7.0.0 | Lance dataset、blob v2、ANN scanner、delete、cleanup |
-| lance-ray | 0.4.2 | 向量索引创建；写回路径暂缓 |
+| pylance | 8.0.0 | Lance dataset、blob v2、ANN scanner、delete、cleanup |
+| lance-ray | 0.4.2 | 向量索引创建；与 pylance 8 的分布式提交兼容性见下方限制 |
 | Ray | 2.55.1 | 由 lance-ray 引入；除非 `USE_RAY=1`，否则 Daft 走 native runner |
 
 Daft 默认 runner 是 `native`（本地多线程）。设置 `USE_RAY=1` 可把 Daft 相关步骤切到 Ray。
@@ -455,8 +455,12 @@ confidence 与 reason 字段在本地行中为 null。VLM 调用失败时仍保
 **本地 Lance URI 已做端到端验证。**
 S3 上的 Lance 表读写由底层库覆盖，但在本 POC 中应作为一个独立的验证项对待。
 
-**blob v2 资产表的 compaction 暂时禁用。**
-当前 `lance-ray 0.4.2` 的向量索引创建依赖 pylance 7.x，而 pylance 8.0.0 虽然修复了 blob v2
-compaction，却改动了 `lance-ray 0.4.2` 仍在调用的分布式索引 commit API。项目暂时锁定
-`pylance<8.0.0`，Stage 5 在删除行之后跳过 compaction。等升级到 pylance 8.x 并配套兼容的
-lance-ray 版本后再重新开启 blob v2 compaction。
+**pylance 8.0.0 与 lance-ray 0.4.2 存在已知的分布式索引限制。**
+pylance 8.0.0 修复了 blob v2 compaction，但移除了 `lance-ray 0.4.2` 在分布式向量索引提交阶段
+调用的 `create_index_segment_builder()`。Stage 3 会捕获该错误并回退到 pylance 本地建索引，
+所以索引功能仍可用，但大表会失去 Ray 分布式建索引的资源扩展能力。等配套兼容的 lance-ray
+版本可用后，应移除这条回退限制。
+
+**blob v2 资产表的 compaction 仍暂时禁用。**
+本次依赖升级不改变 Stage 5 的表管理行为；删除行之后仍跳过 compaction。后续启用时需单独覆盖
+lance-ray、本地 Lance URI 和 MinIO/S3 的 Blob v2 回归验证，避免把版本对齐和行为变更混在一起。

docs/daft-tuning.md

@@ -112,7 +112,9 @@ CPU/网络 在下载下一批图片
 | `LANCE_MAX_BYTES_PER_FILE` | `512MB` | 单个 Lance 数据文件最大字节数。 |
 | `DAFT_JSON_TARGET_FILESIZE` | `128MB` | JSONL 单文件目标大小。 |
 
-为什么要管：碎文件会拖慢后续所有读取，而我们的 pylance 7 禁用了 blob compaction，写坏了没有事后补救，只能在写入侧控制。默认值一般不用动。
+为什么要管：碎文件会拖慢后续所有读取。虽然 pylance 已升级到 8.0.0，Stage 5 仍要等
+lance-ray 和对象存储路径完成独立回归验证后才会开启 blob compaction；在此之前仍应从写入侧
+控制文件布局。默认值一般不用动。
 
 ### 3.7 观测（长任务建议必开）
 

multimodal_toolkit/workflow/manage.py

@@ -1,15 +1,15 @@
-"""Stage 5: manage the lance asset table — delete rows by ingest_time range.
+"""Stage 5：按 ingest_time 范围删除 Lance 资产表中的行。
 
-API priority (lance_ray preferred for table management):
-  delete        → pylance ds.delete()              (no Daft/lance-ray equivalent)
-  compact       → disabled for blob v2 tables until pylance 8 is supported
-  cleanup       → pylance ds.cleanup_old_versions() (no alternative)
+表管理仍遵循项目的数据 API 优先级：
+  delete        → pylance ds.delete()               （Daft/lance-ray 没有等价 API）
+  compact       → 暂不执行；升级 pylance 后仍需单独验证 lance-ray 和对象存储路径
+  cleanup       → pylance ds.cleanup_old_versions() （没有替代 API）
 
-  --before DATE   delete rows where ingest_time < DATE
-  --after  DATE   delete rows where ingest_time > DATE
+  --before DATE   删除 ingest_time < DATE 的行
+  --after  DATE   删除 ingest_time > DATE 的行
 
-DATE format: ISO 8601, e.g. 2025-01-01 or 2025-01-01T00:00:00
-At least one bound must be provided; both can be combined for a date range.
+DATE 使用 ISO 8601 格式，例如 2025-01-01 或 2025-01-01T00:00:00。
+至少传一个边界；两个边界可以组合成日期范围。
 """
 from __future__ import annotations
 
@@ -35,16 +35,17 @@ def delete_by_date(
         clauses.append(f"ingest_time > timestamp '{after}'")
     filter_str = " AND ".join(clauses)
 
-    # delete: pylance only (no Daft/lance-ray equivalent)
+    # 删除目前只有 pylance 提供 API；这里保留直接调用，不能为了统一入口而绕过
+    # Lance 自身的事务提交语义。
     ds = lance.dataset(lance_uri, storage_options=lance_storage_options(lance_uri))
     ds.delete(filter_str)
 
     print(f"[ok] deleted rows where: {filter_str}")
 
-    # Blob v2 tables cannot be compacted safely on pylance 7.x
-    # (lance-format/lance#7071). Keep compaction disabled until the project
-    # can move to pylance 8.x together with a compatible lance-ray release.
-    print("[warn] compaction skipped; enable after upgrading to pylance 8.x")
+    # pylance 8.0.0 已修复 Blob v2 compaction 的解码问题，但版本升级本身不等于
+    # 分布式 compaction 链路已经验证。这里继续跳过，待后续改动同时覆盖 lance-ray、
+    # 本地 Lance URI 和 MinIO/S3 后再开启，避免依赖升级悄悄扩大表管理行为。
+    print("[warn] compaction skipped; enable after validating lance-ray and object storage")
     ds.cleanup_old_versions()
 
 

pyproject.toml

@@ -19,7 +19,7 @@ dependencies = [
   "pillow",
   "psutil",
   "pyarrow",
-  "pylance<8.0.0",
+  "pylance==8.0.0",
   "python-dotenv",
   "ray",
   "soundfile",

tests/workflow/test_index_manage.py

@@ -1,9 +1,8 @@
-"""Tests for workflow/index.py and workflow/manage.py — local lance tables.
+"""在本地 Lance 表上验证 workflow/index.py 和 workflow/manage.py。
 
-build_embedding_index is marked `ray` and excluded from the default run (see
-pyproject) — run it explicitly with `pytest -m ray`. delete_by_date does not
-compact while the project is pinned to pylance 7.x, so those tests stay in the
-default suite.
+build_embedding_index 的真实 Ray 路径不属于默认测试；需要时用 `pytest -m ray`
+显式执行。pylance 已升级到 8.0.0，但 delete_by_date 仍有意不执行 compaction，
+因此删除测试继续留在默认测试集。
 """
 from __future__ import annotations