Dùng CDAF để cung cấp cho tác nhân AI ngữ cảnh video nhanh chóng, đã xác minh

CDAF Làm Gì

CDAF, viết tắt của Cached Descriptive Asset Files (Tệp tài sản mô tả được lưu trong bộ nhớ đệm), là một định dạng sidecar mở dành cho video. Định dạng này lưu trữ mô tả dạng văn bản thuần có dấu thời gian bên cạnh video, sử dụng cùng tên cơ sở. Ví dụ, sunset-drone.mp4 được ghép với sunset-drone.cdaf.

Mục tiêu là mô tả video một lần rồi tái sử dụng mô tả đó cho các tác vụ AI về sau. Thay vì đưa cùng một đoạn phim qua mô hình hiểu video cho mỗi câu hỏi, một tác nhân có thể xác minh và đọc tệp CDAF nhỏ hơn nhiều.

footage/
sunset-drone.mp4
sunset-drone.cdaf

Video gốc không bị thay đổi và vẫn có thể phát bằng phần mềm video thông thường. Sidecar là văn bản UTF-8, gồm một phần đầu siêu dữ liệu nhỏ, theo sau là mô tả Markdown được tối ưu cho các mô hình ngôn ngữ.

Vì Sao Có Thể Tái Sử Dụng Sidecar An Toàn

Phần đầu CDAF ghi lại mã băm SHA-256 và kích thước byte chính xác của video. Các công cụ tuân thủ định dạng sử dụng những giá trị này để xác định mô tả còn hợp lệ hay không. Nếu video thay đổi, sidecar trở nên lỗi thời và không nên được sử dụng.

--- CDAF/1.0
video: sunset-drone.mp4
sha256: 4a7d1ed4…
bytes: 48211394
duration: 00:00:31.500
generator: gemini-2.5-flash
created: 2026-08-26T14:03:12Z
---

## Tóm tắt
Đoạn phim drone từ trên không dài 31 giây, ghi lại một tuyến đường ven biển vào giờ vàng…

## Phân đoạn
[00:00.0-00:05.2] Toàn cảnh từ trên không để giới thiệu bối cảnh…
[00:05.2-00:12.8] Drone tiến gần và hạ thấp độ cao…

## Bản chép lời
(không có lời thoại)

## Văn bản trên màn hình
(không có)

## Thẻ
drone, aerial, coastal highway, golden hour, sunset

Phần nội dung có thể cung cấp bản tóm tắt, các phân đoạn có dấu thời gian, bản chép lời, văn bản trên màn hình và thẻ. Xem đặc tả CDAF 1.0 của dự án để biết định dạng chuẩn, ngữ nghĩa về tính mới, quy tắc lập phiên bản và cú pháp phần.

Tính Năng Chính

• Tái sử dụng có xác minh: Siêu dữ liệu SHA-256 và kích thước byte liên kết sidecar với đúng video mà nó mô tả.
• Định dạng văn bản dễ đọc: Các tác nhân có thể sử dụng, tìm kiếm và tái sử dụng mô tả mà không cần giải mã lại video.
• Phân đoạn có dấu thời gian: Phạm vi phân đoạn có thể hỗ trợ chọn clip và tạo danh sách cắt.
• Lõi không phụ thuộc: Việc phân tích cú pháp, tuần tự hóa, băm, kiểm tra tính mới và trích xuất phân đoạn đều sử dụng thư viện chuẩn Python.
• CLI hướng đến xử lý hàng loạt: Công cụ dòng lệnh có thể tạo sidecar cho một thư mục và bỏ qua những sidecar vẫn còn mới.
• Nhiều hồ sơ mức độ chi tiết: Việc tạo nội dung hỗ trợ đầu ra brief, standard và rich.
• Kỹ năng cho tác nhân: Một skill được đóng gói hướng dẫn các tác nhân lập trình kiểm tra sidecar đã xác minh trước khi phân tích video.
• Tạo cục bộ tùy chọn: Kho mã bao gồm provider --local để tạo nội dung bằng mô hình cục bộ mà không cần khóa API.
• Dò thông tin tùy chọn: CDAF có thể sử dụng ffprobe để lấy siêu dữ liệu về thời lượng, độ phân giải và tốc độ khung hình, đồng thời vẫn hoạt động phù hợp khi ffprobe không khả dụng.

Cài Đặt Skill Cho Tác Nhân

Cách nhanh nhất để dạy cho một tác nhân lập trình được hỗ trợ quy trình ưu tiên sidecar là:

npx cdaf-skill

Mặc định, lệnh này cài skill tại ~/.claude/skills/cdaf, giúp skill khả dụng trên nhiều dự án. Các chế độ cài đặt được hỗ trợ khác gồm:

npx cdaf-skill --project
npx cdaf-skill --dir <path>
npx cdaf-skill --print

• --project cài vào ./.claude/skills/cdaf cho dự án hiện tại.
• --dir cài vào thư mục được chọn.
• --print ghi skill ra đầu ra tiêu chuẩn để có thể dán vào một framework tác nhân khác.

Chạy lại trình cài đặt là an toàn. Skill không thay đổi sẽ được giữ nguyên, còn skill đã sửa sẽ được sao lưu thành SKILL.md.bak trước khi thay thế.

Trước khi phân tích một tệp video, hãy tìm tệp .cdaf có cùng tên cơ sở. Nếu các giá trị phần đầu bytes và sha256 khớp với video, hãy đọc tệp đó thay vì xử lý video.

Cài Đặt CLI CDAF

CLI Python yêu cầu Python 3.10 trở lên. README hiện tại cài đặt CLI trực tiếp từ kho mã vì bản phát hành trên PyPI vẫn nằm trong lộ trình.

pip install "cdaf[generate] @ git+https://github.com/UditAkhourii/cdaf.git#subdirectory=cli"

Nếu đang làm việc từ một kho mã đã sao chép, hãy cài CLI từ thư mục cục bộ cli:

pip install ./cli[generate]

Phần triển khai trình tạo sử dụng Gemini Files API. Lấy khóa API Gemini từ Google AI Studio, sau đó đặt khóa vào môi trường của bạn.

macOS và Linux

export GEMINI_API_KEY=your-key

Windows PowerShell

$env:GEMINI_API_KEY="your-key"

Đoạn phim của bạn được xử lý thông qua khóa API của chính bạn. Các lệnh chỉ đọc hoặc xác minh sidecar hiện có không yêu cầu khóa API hay các dependency của trình tạo.

Tạo Sidecar

Đặt một hoặc nhiều video vào một thư mục rồi chạy cdaf generate trên thư mục đó:

cdaf generate ./footage

CDAF mô tả các video và tạo sidecar có tên cơ sở tương ứng. Khi chạy lại, quá trình tạo sẽ bỏ qua những video có sidecar vẫn còn mới.

Chọn Hồ Sơ Mức Độ Chi Tiết

Sử dụng --detail để chọn một trong ba hồ sơ tạo nội dung được tài liệu hóa:

cdaf generate ./footage --detail brief
cdaf generate ./footage --detail standard
cdaf generate ./footage --detail rich

Chọn một hồ sơ dựa trên lượng ngữ cảnh mô tả mà các tác vụ tiếp theo yêu cầu. Bạn cũng có thể chọn một mô hình Gemini bằng --model hoặc yêu cầu tạo lại bằng --force.

cdaf generate ./footage --model <gemini-model>
cdaf generate ./footage --force

Kiểm tra trạng thái thư viện video

Sử dụng lệnh status để phân loại các tệp sidecar thành FRESH, STALE hoặc MISSING:

cdaf status ./footage

• FRESH: Sidecar khớp với video hiện tại.
• STALE: Sidecar tồn tại, nhưng danh tính được ghi lại không còn khớp với video.
• MISSING: Không có sidecar CDAF tương ứng.

Lệnh này không cần khóa API hay các dependency tạo nội dung, phù hợp để kiểm tra nhanh các thư viện tài sản hiện có.

Đọc mô tả đã xác minh

Sử dụng cdaf read khi bạn muốn lấy nội dung sidecar cho agent, tập lệnh hoặc prompt:

cdaf read ./footage/sunset-drone.mp4

Lệnh này xác minh hash trước khi in mô tả. Lệnh sẽ từ chối in sidecar cũ, đảm bảo quy tắc về tính mới được thực thi trong công cụ thay vì chỉ dựa vào hướng dẫn dành cho agent.

Xác thực sidecar trong quy trình tự động hóa

Lệnh validation chỉ thoát thành công khi sidecar tương ứng vừa đúng định dạng vừa còn mới:

cdaf validate ./footage/clip.mp4

Vì lệnh chỉ thoát với mã trạng thái 0 khi sidecar hợp lệ và còn mới, bạn có thể sử dụng lệnh này trong các tập lệnh hoặc quy trình tích hợp liên tục. Việc xác thực không cần khóa API hay các dependency tạo nội dung tùy chọn.

Sử dụng CDAF từ Python

API Python cốt lõi cho phép ứng dụng định vị, tải và xác minh sidecar trước khi chuyển nội dung của nó cho mô hình ngôn ngữ.

from cdaf import load, check_freshness, sidecar_path_for

video = "footage/sunset-drone.mp4"
sidecar = load(sidecar_path_for(video))

if check_freshness(video, sidecar) == "fresh":
    context_for_llm = sidecar.body

Mẫu này là cách tích hợp CDAF cốt lõi: suy ra đường dẫn sidecar dự kiến, phân tích tệp, xác minh tính mới dựa trên video và chỉ sử dụng sidecar.body khi kết quả là fresh.

Phần lõi của gói cũng hỗ trợ tuần tự hóa, tính SHA-256 theo từng khối và trích xuất phân đoạn. Các thao tác này chỉ sử dụng thư viện chuẩn. Mã dành riêng cho trình tạo chỉ được nhập khi có yêu cầu tạo nội dung.

Xây dựng quy trình agent ưu tiên sidecar

1. Nhận đường dẫn video như một phần của tác vụ chỉnh sửa, tìm kiếm hoặc hỏi đáp.
2. Tìm tệp .cdaf có cùng tên cơ sở.
3. Kiểm tra tính mới của sidecar dựa trên video hiện tại.
4. Nếu sidecar còn mới, đọc văn bản của nó thay vì chạy thêm một lượt phân tích video.
5. Nếu sidecar cũ hoặc bị thiếu, hãy tạo lại trước khi sử dụng nội dung của nó.
6. Sử dụng bản tóm tắt, các phân đoạn, bản chép lời, văn bản trên màn hình và thẻ làm ngữ cảnh cho tác vụ tiếp theo.

Kỹ năng agent đi kèm gói đề xuất kiểm tra kích thước nhanh trong quá trình khám phá và kiểm tra hash đầy đủ cho các quyết định quan trọng. Ứng dụng nên sử dụng mức độ xác minh phù hợp với thao tác, đồng thời duy trì quy tắc cốt lõi rằng không được tin cậy các mô tả cũ.

Mẹo nâng cao

Tìm kiếm bộ sưu tập video dưới dạng văn bản

Sau khi video có sidecar, agent và công cụ dòng lệnh có thể tìm kiếm các tệp .cdaf thay vì mở từng video. Thẻ và mô tả có thể chuyển các yêu cầu như cảnh hoàng hôn ven biển không có người thành truy xuất văn bản trong thư viện tài sản.

Biến các phân đoạn thành quyết định chỉnh sửa

Các dòng có dấu thời gian như [00:05.2-00:12.8] cung cấp các khoảng thời gian mà trình chỉnh sửa lập trình có thể chuyển thành clip hoặc chuỗi cảnh. README nêu rõ Remotion, HyperFrames và các công cụ chuyển prompt thành bản chỉnh sửa là những quy trình có thể hưởng lợi từ cấu trúc này.

Tái sử dụng thời gian của bản chép lời

Khi có lời thoại, phần Transcript căn chỉnh lời nói với dòng thời gian. Quy trình chỉnh sửa có thể tái sử dụng thông tin này cho phụ đề và đồng bộ hóa âm thanh thay vì thực hiện thêm một lượt phân tích.

Sử dụng siêu dữ liệu ffprobe tùy chọn

Nếu ffprobe khả dụng, thành phần probe của CDAF có thể thu thập siêu dữ liệu về thời lượng, độ phân giải và số khung hình mỗi giây. Engine vẫn hoạt động bình thường khi thiếu ffprobe, nên tích hợp tùy chọn này không cản trở các thao tác sidecar cơ bản.

Cân nhắc việc tạo nội dung cục bộ

Kho lưu trữ bao gồm một provider cục bộ được cung cấp qua --local. Provider này dành cho việc tạo nội dung bằng mô hình cục bộ khi không nên sử dụng khóa API. Hãy tham khảo phần triển khai provider cục bộ của kho lưu trữ để biết thiết lập mô hình cục bộ hiện được hỗ trợ.

Tách backend khỏi định dạng

Bản thân CDAF không phụ thuộc mô hình. Gemini là backend tạo nội dung từ xa được tích hợp, trong khi các backend mô hình ngôn ngữ-video khác có thể hoạt động phía sau cùng một kiểu Sidecar. Các backend Claude, GPT và VLM cục bộ bổ sung được liệt kê trong lộ trình và chưa nên được giả định là đã khả dụng.

Tái tạo benchmark

Kho lưu trữ bao gồm một benchmark khách quan, tạo video từ các công thức được lập trình bằng ffmpeg. Chạy các giai đoạn theo thứ tự:

python benchmarks/bench.py make
python benchmarks/bench.py run
python benchmarks/bench.py report

Bước đầu tiên yêu cầu ffmpeg, bước thứ hai yêu cầu GEMINI_API_KEY, và bước cuối cùng ghi vào benchmarks/RESULTS.md. Trong bài kiểm thử 20 câu hỏi được báo cáo, các câu trả lời sidecar đạt 20/20 câu đúng, so với 19/20 của video trực tiếp, đồng thời sử dụng trung bình 303 thay vì 3.066 token prompt cho mỗi câu hỏi. Đây là kết quả benchmark từ kho lưu trữ và có thể thay đổi tùy theo cảnh quay, mô hình, prompt và môi trường.

Hạn Chế Hiện Tại Và Lộ Trình

README xác định một số hạng mục là công việc trong tương lai thay vì chức năng hiện tại: bản phát hành PyPI, máy chủ MCP, trình chuyển đổi được lưu trữ, các backend tạo bổ sung, bản chuyển engine Node hoặc TypeScript, mở rộng benchmark với cảnh quay tự nhiên và sidecar được ký. Hiện nay, hãy sử dụng phương thức cài đặt Python dựa trên Git và CLI hiện có theo tài liệu, thay vì giả định rằng các thành phần trong lộ trình đã khả dụng.

Kết Luận

CDAF chuyển việc phân tích video lặp đi lặp lại thành quy trình xác minh rồi đọc. Hãy tạo sidecar một lần, giữ nó bên cạnh video nguồn, xác thực mỗi khi tài sản được sử dụng và cung cấp phần nội dung của nó cho các agent hạ nguồn. Các mã băm của định dạng ngăn việc vô tình tái sử dụng sau khi chỉnh sửa, trong khi phần tóm tắt, dấu thời gian, bản chép lời, văn bản và thẻ giúp thư viện video dễ tìm kiếm và tự động hóa hơn.

CDAF được cung cấp theo Giấy phép MIT. Mã nguồn, đặc tả, các ví dụ, thông tin chi tiết về benchmark và kỹ năng dành cho agent có sẵn trong kho CDAF trên GitHub.