Tại sao lỗi này xảy ra
Gặp lỗi 422 Unprocessable Entity khi thiết lập một collection trong Qdrant thường có nghĩa là cấu hình vectors của bạn không đúng về mặt cấu trúc. Engine dựa trên Rust của Qdrant cực kỳ nghiêm ngặt về schema. Nếu server mong đợi một cấu trúc object cụ thể nhưng lại nhận được một dictionary thô hoặc một danh sách lồng nhau sai cách, nó sẽ từ chối yêu cầu ngay lập tức. Điều này thường xảy ra khi các nhà phát triển chuyển từ phiên bản client cũ hơn hoặc nhầm lẫn giữa logic "Single Vector" và "Named Vector".
Thông thường, nguyên nhân nằm ở JSON payload. API mong đợi một object VectorParams có cấu trúc (hoặc một bản đồ của chúng), nhưng mã nguồn có khả năng đang gửi một dictionary Python thuần túy không khớp chính xác với các định nghĩa Protobuf hoặc REST nội bộ.
Các lỗi thường gặp
1. Bẫy "Dictionary thuần"
Bạn có thể muốn truyền một dictionary thô vào đối số vectors. Bạn có thể cho rằng client sẽ tự động parse nó, nhưng điều này thường dẫn đến lỗi xác thực:
# Điều này có khả năng sẽ kích hoạt lỗi 422
client.create_collection(
collection_name="my_collection",
vectors={
"size": 1536,
"distance": "Cosine"
}
)
2. Nhầm lẫn về Named Vector
Khi sử dụng nhiều vector cho mỗi điểm—như có một vector cho văn bản và một vector khác cho các đặc trưng hình ảnh—bạn phải cung cấp một dictionary trong đó mỗi key ánh xạ tới một instance VectorParams. Nếu bạn cung cấp một object đơn lẻ trong khi hệ thống mong đợi một bản đồ (map), quá trình xác thực sẽ thất bại.
Cách khắc phục
Cách 1: Cấu hình Single Vector chính xác
Đối với thiết lập tiêu chuẩn với một vector cho mỗi điểm, hãy sử dụng class models.VectorParams. Đây là cách an toàn nhất để đảm bảo mã Python của bạn tạo ra chính xác cấu trúc JSON mà server yêu cầu.
from qdrant_client import QdrantClient, models
client = QdrantClient("localhost", port=6333)
client.create_collection(
collection_name="my_docs",
vectors=models.VectorParams(
size=1536, # Ví dụ: 1536 cho OpenAI text-embedding-3-small
distance=models.Distance.COSINE
)
)
Cách 2: Xử lý Named Vector đúng cách
Nếu dự án của bạn yêu cầu tìm kiếm đa phương thức (multi-modal search), hãy bọc mỗi cấu hình vector trong VectorParams bên trong một dictionary. Điều này cho Qdrant biết rõ ràng kích thước (dimensions) nào thuộc về index được đặt tên nào.
from qdrant_client import QdrantClient, models
client = QdrantClient("localhost", port=6333)
client.create_collection(
collection_name="multi_modal_collection",
vectors={
"text-features": models.VectorParams(size=768, distance=models.Distance.COSINE),
"image-features": models.VectorParams(size=512, distance=models.Distance.EUCLID)
}
)
Cách 3: Debug REST API Payloads
Nếu bạn không dùng Python client mà sử dụng curl hoặc requests, hãy kiểm tra cấu trúc lồng nhau. Một thiết lập single vector sẽ trông như thế này:
{
"vectors": {
"size": 1536,
"distance": "Cosine"
}
}
Tránh thêm các key bổ sung như "my_vector" bên trong object vectors trừ khi bạn thực sự có ý định sử dụng named vectors trong toàn bộ pipeline tìm kiếm của mình.
Xác minh giải pháp
Sau khi cập nhật mã, hãy chạy đoạn mã này để xác nhận collection đang hoạt động tốt:
collection_info = client.get_collection(collection_name="my_docs")
print(f"Trạng thái: {collection_info.status}")
print(f"Cấu hình Vector: {collection_info.config.params.vectors}")
Trạng thái green hoặc yellow có nghĩa là lỗi 422 đã được giải quyết và collection của bạn đã sẵn sàng để nạp dữ liệu (upserts).
Mẹo phòng ngừa
- **Xác minh kích thước (Dimensions):** Luôn khớp `size` với model cụ thể của bạn. OpenAI `text-embedding-3-small` sử dụng 1536, trong khi `text-embedding-3-large` mặc định là 3072. HuggingFace `all-MiniLM-L6-v2` sử dụng 384.
- **Sử dụng Enums:** Tránh nhập các chuỗi như "Cosine" một cách thủ công. Sử dụng `models.Distance.COSINE` để ngăn chặn lỗi đánh máy.
- **Xác thực các cấu hình phức tạp:** Nếu bạn đang thêm các cài đặt HNSW hoặc quantization, JSON sẽ trở nên lộn xộn rất nhanh. Tôi thường chạy các object cấu hình của mình qua một [JSON Formatter & Validator](https://toolcraft.app/en/tools/developer/json-formatter) trước khi triển khai. Nó giúp phát hiện các dấu phẩy thừa và lỗi lồng nhau dẫn đến phản hồi 422.
- **Cập nhật Client:** Qdrant phát triển rất nhanh. Hãy chạy `pip install -U qdrant-client` để đảm bảo thư viện local của bạn không gửi các cấu trúc payload đã cũ đến phiên bản server mới hơn.