Hướng dẫn chuyển đổi từ Chroma Cloud sang Pinecone

← Blog Hướng dẫn chuyển đổi từ Chroma Cloud sang Pinecone Chuyển đổi tập hợp dữ liệu Chroma Cloud sang chỉ mục không máy chủ của Pinecone Aaron Kao Ngày 26/10/2026 Sản phẩm Chia sẻ: Chuyển đến phần: Nội dung chính của hướng dẫn Đối chiếu các khái niệm giữa Chroma và Pinecone Quy trình chuyển đổi Tạo lại véc-tơ nhúng sau khi chuyển đổi Gói dùng thử Pinecone Standard trị giá 300 USD Giải pháp thay thế cho người dùng Chroma Cloud Chia sẻ: Đăng ký nhận tin từ Pinecone Nhận thông tin cập nhật mới nhất qua thư điện tử ngay khi được xuất bản: Nhận bản tin cập nhật Chroma Cloud sẽ ngừng tiếp nhận lệnh ghi dữ liệu vào ngày 22/11/2026 và ngừng cung cấp dịch vụ đọc dữ liệu vào ngày 22/12/2026. Tài liệu này hướng dẫn cách chuyển đổi một tập hợp dữ liệu (collection) sang cơ sở dữ liệu Pinecone Database trong thời gian tạm dừng ghi theo kế hoạch. Chroma đang tiến hành ngừng cung cấp Chroma Cloud, dịch vụ máy chủ lưu trữ chuyên dụng của đơn vị này. Thông báo từ Chroma xác định hai mốc thời gian: Ngày 22/11/2026: Ngừng thao tác ghi. Chroma Cloud chuyển sang chế độ chỉ đọc. Không thể tạo mới, cập nhật hoặc xóa dữ liệu. Ngày 22/12/2026: Ngừng thao tác đọc. Chroma Cloud chấm dứt việc tiếp nhận và xử lý các truy vấn. Chroma khuyến nghị người dùng bắt đầu xuất và xác thực dữ liệu trước ngày 22/11 và hoàn tất trước ngày 22/12. Phiên bản mã nguồn mở của Chroma không bị ảnh hưởng và tiếp tục được cung cấp theo giấy phép Apache 2.0. Đối với các đơn vị có nhu cầu sử dụng dịch vụ được quản trị toàn diện thay vì tự vận hành Chroma, Pinecone Database cung cấp giải pháp không máy chủ (serverless) và được quản lý hoàn toàn. Hệ thống không đòi hỏi vận hành cụm máy chủ, cũng như không yêu cầu định cỡ hoặc cấp phát tài nguyên chỉ mục trước khi nạp dữ liệu. Thông tin chi tiết về kiến trúc hệ thống có thể tham khảo tại đây. Người dùng Chroma Cloud hiện có thể bắt đầu sử dụng gói dùng thử Pinecone Standard trong 3 tuần với hạn mức 300 USD. Nội dung chính của hướng dẫn Tài liệu hướng dẫn quy trình chuyển một tập hợp dữ liệu Chroma Cloud đã có sẵn các véc-tơ nhúng dày đặc (dense embeddings), văn bản tài liệu và siêu dữ liệu (metadata) sang chỉ mục không máy chủ của Pinecone. Phương pháp này tái sử dụng toàn bộ các véc-tơ hiện có và không yêu cầu tạo lại véc-tơ nhúng. Quy trình giả định hệ thống có kế hoạch tạm dừng thao tác ghi: ứng dụng sẽ duy trì trạng thái chỉ đọc trong suốt thời gian chuyển đổi. Trường hợp cần chuyển đổi nhiều tập hợp dữ liệu, thao tác được lặp lại tuần tự cho từng tập hợp. Quá trình xử lý vận hành thông qua bộ công cụ gồm 6 tệp lệnh Python: kiểm tra sơ bộ (preflight), tạo chỉ mục (create index), xuất dữ liệu (export), chuyển đổi (convert), nạp dữ liệu (load) và xác thực (validate). Bộ công cụ được phát hành tại pinecone-field/chromacloud-migration. Bộ công cụ này được cung cấp theo nguyên trạng và không đi kèm bất kỳ cam kết bảo đảm nào. Mã nguồn có thể không hoàn toàn tương thích với cấu trúc dữ liệu, cấu hình nhúng hoặc kế hoạch chuyển đổi của từng hệ thống cụ thể. Trước khi tạm ngưng tiếp nhận lệnh ghi hoặc chuyển đổi lưu lượng thực tế của hệ thống, người vận hành cần tự chạy thử nghiệm các tệp lệnh trên tập dữ liệu nội bộ, rà soát toàn bộ kết quả phát sinh và xác nhận quy trình kiểm tra đáp ứng đúng yêu cầu của ứng dụng. Người dùng chịu trách nhiệm xác thực tính hiệu quả của phương án chuyển đổi đối với từng trường hợp sử dụng cụ thể. Thực hiện bằng tác tử lập trình (Coding Agent) Quá trình chuyển đổi cũng có thể được bàn giao cho các tác tử lập trình như Claude Code, Cursor hoặc Codex thực hiện. Bộ công cụ tích hợp sẵn một kỹ năng trong gói Agent Skills nhằm hướng dẫn tác tử thực hiện tuần tự các bước tương tự tài liệu này. Thao tác cài đặt từ kho lưu trữ của bộ công cụ được thực hiện bằng lệnh: npx skills add pinecone-field/chromacloud-migration Sau khi quá trình cài đặt hoàn tất, hệ thống sẽ thực hiện chuyển đổi tập hợp dữ liệu (collection) từ Chroma Cloud sang Pinecone thông qua việc vận hành tuần tự sáu tập lệnh. Ánh xạ các khái niệm giữa Chroma và Pinecone Dưới đây là một số khái niệm, thuật ngữ trọng tâm trong Chroma Cloud và các thuật ngữ tương đương trên Pinecone: Chroma | Pinecone: Tenant / database | Organization / project; Collection | Index, hoặc namespace trong một index dùng chung khi các collection có cùng kích thước (dimension) và hệ đo (metric); ids | _id: từ 1 đến 512 ký tự ASCII, không chứa ký tự NUL, các ID khác sẽ được tạo mới; embeddings | Trường dense_vector có tên embedding, được khai báo trong lược đồ (schema) của index; documents | Trường text của tài liệu; metadatas | Các trường dữ liệu cấp cao nhất của tài liệu, tự động lọc được, giá trị là chuỗi, số, boolean hoặc danh sách chuỗi; Distance l2 (mặc định) / cosine / ip | Metric euclidean / cosine / dotproduct; bộ lọc where | bộ lọc với $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $and, $or, $not; $contains / $not_contains đối với khóa mảng | {"$in": [giá trị]} / {"$nin": [giá trị]}; $contains / $not_contains đối với khóa không phải mảng, where_document | Không có trường tương đương, cần thiết kế lại các truy vấn này. Một số dữ liệu sẽ thay đổi trong quá trình chuyển sang Pinecone, chẳng hạn như ID được ánh xạ lại, các khóa metadata được đổi tên và các bộ lọc cần được thiết kế lại. Tệp README của kho lưu trữ đã liệt kê cụ thể từng trường hợp. Trình tự di chuyển dữ liệu Quy trình chuyển đổi collection từ Chroma Cloud sang cơ sở dữ liệu Pinecone gồm 10 bước: Bước 1: Diễn tập và ước lượng khung thời gian - chạy preflight.py, sau đó chạy thử nghiệm toàn diện (dry run); Bước 2: Tạo index và triển khai khóa chuyển đổi đọc/ghi - chạy create_index.py; Bước 3: Tạm dừng quyền ghi, duy trì quyền đọc trên Chroma - thực hiện trên ứng dụng nghiệp vụ, sau đó chạy preflight.py; Bước 4: Chụp nhanh số lượng và xuất dữ liệu - chạy export.py; Bước 5: Chuyển đổi, sau đó nạp dữ liệu vào một namespace mới - chạy convert.py, load.py; Bước 6: Xác thực tính chính xác - chạy validate.py; Bước 7: Phê duyệt quyết định chuyển đổi - nhân sự phụ trách; Bước 8: Chuyển đổi đồng thời cả quyền đọc và ghi - thực hiện trên ứng dụng nghiệp vụ; Bước 9: Giám sát hệ thống sau khi chuyển giao - nhân sự phụ trách; Bước 10: Ngừng vận hành Chroma Cloud - thực hiện trên ứng dụng nghiệp vụ và tài khoản quản trị. Thiết lập từ thư mục gốc của bộ công cụ bằng uv để cài đặt các gói phụ thuộc cố định phiên bản: uv sync export PINECONE_API_KEY=... # áp dụng cho toàn bộ các bước của Pinecone export CHROMA_API_KEY=... CHROMA_TENANT=... CHROMA_DATABASE=... # Chroma Cloud Các lệnh mẫu sử dụng collection mang tên my_collection, index mang tên my-index và namespace mang tên my-collection-v1. Cần thay thế các giá trị này bằng thông số thực tế. Các tập lệnh đọc dữ liệu từ Chroma sẽ gọi chromadb.CloudClient(), nạp ba biến môi trường CHROMA_*. Để kiểm thử với bản sao Chroma mã nguồn mở cục bộ, bổ sung tùy chọn --chroma-path PATH vào các tập lệnh đó. Bước 1: Diễn tập Tập lệnh preflight tiến hành quét từng trang của collection. Quá trình này báo cáo collection.count(), kích thước nhúng (embedding dimension), không gian khoảng cách (distance space), hàm nhúng đã ghi nhận, toàn bộ các khóa metadata kèm kiểu giá trị và tên trường đích tương ứng trên Pinecone, các tài liệu rỗng hoặc nhận giá trị None, cùng những ID không hợp lệ đối với Pinecone. Các phát hiện được phân loại thành BLOCKING, TRANSFORM, WARNING hoặc INFO và được lưu trữ tại tệp preflight.json. uv run preflight.py --collection my_collection --workdir migration_work uv run preflight.py --collection my_collection --workdir migration_work --allow-transforms # sau khi kiểm tra các phát hiện TRANSFORM Cần rà soát các phát hiện từ lượt chạy đầu tiên. Các phát hiện thuộc nhóm BLOCKING sẽ trả về mã thoát lỗi (exit 1), bao gồm: vector chứa toàn số 0, kích thước không đồng nhất, metadata vượt quá 40 KB, các kiểu dữ liệu không được hỗ trợ, cùng các mảng kiểu số hoặc boolean. Những lỗi này cần được xử lý dứt điểm trên Chroma trước khi tạm dừng dịch vụ. Các trường hợp thuộc nhóm TRANSFORM (ID mới, khóa được đổi tên, lược bỏ giá trị None) cũng sẽ trả về mã exit 1 cho đến khi được xác nhận bằng tùy chọn --allow-transforms. Trường hợp preflight báo lỗi metadata_over_40kb do văn bản tài liệu quá dài, cần chuyển sang biến thể tìm kiếm toàn văn (full-text-search) tại Bước 2, hoặc chia nhỏ văn bản từ nguồn dữ liệu. Bổ sung tham số --