Ngừng hỗ trợ GraphQL API: Lộ trình và các phương án chuyển đổi

GraphQL từng là API truy vấn đầu tiên của Weaviate và đã được triển khai rộng rãi kể từ những phiên bản đầu. Hiện nay, giao diện này chính thức bước vào giai đoạn ngừng hỗ trợ (deprecate). Hoạt động hiện tại của hệ thống không bị gián đoạn. Các cụm máy chủ (cluster) đang sử dụng GraphQL sẽ tiếp tục duy trì đến ngày 1/5/2027 - thời điểm kết thúc vòng đời của GraphQL trên Weaviate Cloud. Đội ngũ kỹ thuật sẵn sàng hỗ trợ quá trình chuyển đổi. Người dùng có thể liên hệ bộ phận hỗ trợ qua cổng thông tin hoặc thư điện tử support@weaviate.io đối với mọi mô hình cài đặt. Tài liệu hướng dẫn chuyển đổi GraphQL cung cấp các bước chi tiết, bài viết này giải thích nguyên nhân, lộ trình thực hiện và các phương án lựa chọn. Tóm tắt nội dung API GraphQL chính thức ngừng hỗ trợ từ ngày 26/10/2026. Mọi hoạt động trong ngày này vẫn diễn ra bình thường. Weaviate Cloud sẽ ngừng kích hoạt GraphQL trên toàn bộ các cụm máy chủ vào ngày 1/5/2027. Ngày 1/5/2027 là thời điểm kết thúc vòng đời của GraphQL trên Weaviate Cloud. Trường hợp cụm máy chủ không sử dụng GraphQL trong 30 ngày gần nhất, tính năng này sẽ bị tắt từ ngày 1/12/2026. Các cụm máy chủ Weaviate Cloud mới tạo hiện đã không còn tích hợp GraphQL. Thông báo qua thư điện tử đang được gửi tới toàn bộ khách hàng Weaviate Cloud để xác định cụ thể các cụm máy chủ chịu ảnh hưởng. Người dùng Weaviate Cloud khi cần hỗ trợ có thể liên hệ qua cổng hỗ trợ hoặc địa chỉ support@weaviate.io. Mọi phiên bản Weaviate phát hành trước ngày 1/5/2027 vẫn duy trì hoạt động của API GraphQL. Bản phát hành phụ (minor release) đầu tiên sau mốc thời gian này sẽ tắt tính năng theo mặc định, nhưng người dùng vẫn có thể kích hoạt lại. Tính năng sẽ bị loại bỏ hoàn toàn trong các bản phát hành tiếp theo. Trường hợp ứng dụng thực hiện truy vấn thông qua các thư viện máy khách (client) phiên bản hiện hành của Python, TypeScript, Java hoặc C#, hệ thống gần như không bị ảnh hưởng. Các trường hợp còn lại cần thực hiện theo tài liệu hướng dẫn chuyển đổi. Hiện đại hóa API truy vấn của Weaviate GraphQL đã phục vụ hiệu quả cho Weaviate và người dùng trong thời gian dài. Giao thức này cung cấp một ngôn ngữ trực quan cho mọi phương thức tìm kiếm và là nền tảng cho nhiều giải pháp xây dựng trên Weaviate. Quá trình chuyển đổi sang một API truy vấn hiện đại mang lại các lợi ích sau: Tốc độ: gRPC truyền tải Protocol Buffers dạng nhị phân qua giao thức HTTP/2, giúp các truy vấn tiết kiệm băng thông và phản hồi nhanh hơn so với định dạng JSON qua HTTP. Bài viết chuyên môn về hiệu năng gRPC cung cấp các số liệu đo lường cụ thể. Giao ước rõ ràng: Các thông điệp định kiểu dữ liệu (typed messages) cung cấp kết quả có định kiểu và các đối tượng yêu cầu được tạo tự động cho từng máy khách, loại bỏ việc phải ghép chuỗi truy vấn hoặc phân tích cú pháp JSON lồng nhau. Lỗi được trả về dưới dạng mã trạng thái thực tế thay vì mã HTTP 200 kèm mảng lỗi (errors array). Dữ liệu đặc tả (metadata) là một trường trực tiếp trên kết quả, không còn nằm trong khối _additional riêng biệt. Bảo mật phù hợp với cơ chế phân quyền chi tiết: Tính năng thăm dò (introspection) của GraphQL đòi hỏi quyền đọc trên toàn bộ các tập hợp (collection). Điều này không tương thích với mô hình kiểm soát truy cập dựa trên vai trò (RBAC) theo từng tập hợp. Các API gRPC và REST kiểm tra chính xác tập hợp được truy vấn. Phù hợp với phương thức truy vấn hiện đại: Thế mạnh của GraphQL trước đây là ngôn ngữ truy vấn dễ đọc và có thể nhập thủ công. Hiện nay, phần lớn truy vấn được tạo tự động bởi các thư viện máy khách, khung phát triển (framework) và các tác tử (agent). Giao thức nhị phân tinh gọn và API JSON thuần túy đáp ứng các hệ thống này hiệu quả hơn so với ngôn ngữ truy vấn thủ công. Việc chuẩn hóa về một API duy nhất cũng đồng nghĩa với việc mọi tính năng tìm kiếm chỉ cần phát triển, kiểm thử và lập tài liệu một lần, giúp đẩy nhanh tiến độ phát hành các bản nâng cấp. Lộ trình thực hiện Các trường hợp chịu ảnh hưởng Việc thay đổi chỉ tác động đến các hệ thống gửi truy vấn tới Weaviate thông qua GraphQL. Các tiêu chí xác định bao gồm: Mã nguồn nội bộ trực tiếp gửi truy vấn GraphQL: Hệ thống gửi trực tiếp các yêu cầu HTTP tới địa chỉ /v1/graphql. Hệ thống gọi hàm hỗ trợ GraphQL thô trong thư viện máy khách, ví dụ như graphql_raw_query() trong Python. Mã chạy trên trình duyệt của ứng dụng gửi các truy vấn GraphQL. Thư viện máy khách hoặc công cụ trung gian tự động gửi truy vấn: Các phiên bản thư viện cũ: API Python v3 (weaviate.Client), weaviate-ts-client v2, Java client v5, hoặc Go client phiên bản v5 trở về trước gửi truy vấn qua GraphQL. Công cụ no-code hoặc công cụ phân tích kinh doanh (BI) gửi truy vấn GraphQL tới cụm máy chủ (cluster). Tài liệu hướng dẫn cung cấp phương pháp xác định mức độ sử dụng GraphQL. Trường hợp truy cập Weaviate qua các khung làm việc (framework) như LangChain hoặc LlamaIndex, cần sử dụng gói tích hợp chính thức của Weaviate được xây dựng trên thư viện máy khách hiện hành. Các gói do cộng đồng phát triển có thể vẫn gửi truy vấn GraphQL. Các giải pháp thay thế Thư viện máy khách (Khuyến nghị) Các thư viện máy khách Python, TypeScript, Java và C# hiện hành thực hiện tìm kiếm qua giao thức gRPC; đây là phương án được khuyến nghị áp dụng. Đối với Go, giải pháp chuyển đổi là sử dụng thư viện máy khách v6 có tích hợp gRPC. Tham khảo chi tiết tại mục thư viện máy khách trong tài liệu hướng dẫn. Thư viện web client TypeScript Đối với trình duyệt và các môi trường thực thi biên (edge runtime) không thể mở kết nối gRPC trực tiếp, thư viện web client TypeScript (@weaviate/web) sử dụng gRPC-Web. Thư viện này hiện đã được cung cấp với giao diện API tương tự phiên bản Node. Tham khảo mục thư viện TypeScript cho web. API Tìm kiếm REST Đối với các ngăn xếp công nghệ hoàn toàn không thể vận hành thư viện máy khách, API Tìm kiếm REST cung cấp các điểm cuối JSON thuần phục vụ tìm kiếm và tổng hợp dữ liệu (tham khảo tài liệu API REST). Tính năng này hiện ở giai đoạn Xem trước (Preview). Đây là tập hợp con của các tính năng GraphQL, do đó cần rà soát các truy vấn chưa có phương thức REST tương đương trước khi bắt đầu triển khai. Hiện tại, một số tính năng chuyên biệt của GraphQL chưa có giải pháp thay thế tương đương. Tài liệu hướng dẫn liệt kê cụ thể các tính năng này tại mục "Tính năng GraphQL chưa có phương thức tương đương". Đơn vị cam kết đáp ứng các nhu cầu thực tế của khách hàng. Trường hợp phát sinh các chức năng cần thiết chưa được hỗ trợ, người dùng có thể liên hệ bộ phận hỗ trợ kỹ thuật để được xem xét bổ sung. Lộ trình chuyển đổi Tài liệu hướng dẫn chuyển đổi cung cấp bảng đối chiếu các truy vấn GraphQL sang phương thức thay thế tương ứng. Thời gian từ khi thông báo ngừng hỗ trợ đến khi kết thúc vòng đời dịch vụ trên Weaviate Cloud là sáu tháng, tạo điều kiện thuận lợi để xây dựng kế hoạch chuyển đổi theo chu kỳ phát hành nội bộ. Người dùng có thể chủ động tắt tính năng GraphQL trên phiên bản cài đặt độc lập ngay hôm nay để kiểm tra tính toàn vẹn của hệ thống. Xác định các lệnh gọi GraphQL: Rà soát mã nguồn, máy chủ ủy quyền (proxy) và công cụ đối với đường dẫn /v1/graphql và các hàm hỗ trợ GraphQL thô. Tham khảo mục xác định mức độ sử dụng GraphQL. Lựa chọn giải pháp: Sử dụng thư viện máy khách khi có thể, thư viện web client TypeScript trên môi trường trình duyệt, và API Tìm kiếm REST khi cả hai phương án trên không phù hợp. Tài liệu hướng dẫn cung cấp bảng tiêu chí ra quyết định cho nội dung này. Chuyển đổi truy vấn: Sử dụng tài liệu hướng dẫn chuyển đổi để chuẩn hóa các truy vấn GraphQL hiện tại sang các phương thức thay thế. Kiểm tra khi vô hiệu hóa GraphQL: Vận hành ứng dụng trên phiên bản Weaviate đã tắt tính năng GraphQL. Trên Weaviate Cloud, liên hệ bộ phận hỗ trợ kỹ thuật để tắt GraphQL trên cụm máy chủ được chỉ định nhằm tiến hành kiểm thử. Tham khảo mục kiểm thử khi vô hiệu hóa GraphQL. Một truy vấn, bốn phương thức thực hiện: Dưới đây là một thao tác tìm kiếm gần đúng theo văn bản (near-text) trên tập hợp Movie, được triển khai theo bốn cách: năm bộ phim thể loại "space opera" từ năm 1980 trở đi