Sửa lỗi Pinecone NotFoundException: Không tìm thấy Index 'my-index' trong Project

Tình huống lỗiLỗi này có thể xảy ra với bất kỳ ai. Bạn đang xây dựng một pipeline RAG hoặc một công cụ tìm kiếm vector, và mọi thứ có vẻ ổn. Bạn đã có API key, index hiển thị rõ ràng trên dashboard, và mã nguồn trông rất chuẩn. Tuy nhiên, khi chạy script, nó lại gặp lỗi với traceback sau:

pinecone.exceptions.NotFoundException: Index 'my-index' not found in project

Điều này thường xảy ra ngay khi bạn gọi hàm pc.Index("my-index"). Đây là một lỗi gây khó chịu vì bảng điều khiển web của Pinecone có thể hiển thị index ở trạng thái "Ready" (Sẵn sàng), nhưng Python SDK lại khẳng định rằng nó không tồn tại.

Các nguyên nhân phổ biếnLỗi NotFoundException hiếm khi là lỗi từ hạ tầng của Pinecone. Thay vào đó, nó hầu như luôn là do sự sai lệch cấu hình giữa môi trường cục bộ và project trên Pinecone Cloud. Dưới đây là các nguyên nhân khả thi nhất:

• Phân biệt chữ hoa chữ thường: Tên index trong Pinecone phân biệt chữ hoa chữ thường rất nghiêm ngặt. Nếu index của bạn tên là Knowledge-Base nhưng bạn gọi pc.Index("knowledge-base"), yêu cầu sẽ thất bại.- Nhầm lẫn API Key: Bạn có thể đang dùng API key từ một project "Development" để cố gắng truy cập vào một index nằm trong project "Production". Mỗi API key chỉ có phạm vi hiệu lực trong một project cụ thể.- Chu kỳ tạm dừng của gói "Starter": Nếu bạn dùng gói Free Starter, Pinecone sẽ tạm dừng các index sau 7 ngày không hoạt động. Một index bị tạm dừng thường trả về lỗi 404 cho đến khi được khôi phục thủ công.- Lan truyền DNS: Với các index Serverless mới, có thể mất từ 30 đến 60 giây để URL host lan truyền qua DNS. Nếu bạn kết nối ngay lập tức sau khi tạo, SDK sẽ không tìm thấy nó.## Khắc phục nhanh: Kiểm tra khả năng hiển thịTrước khi đi sâu vào gỡ lỗi, hãy chạy script chẩn đoán này. Nó buộc SDK phải cho bạn biết chính xác những gì nó có thể nhìn thấy bằng API key hiện tại của bạn:

from pinecone import Pinecone

# Khởi tạo với key hiện tại của bạn
pc = Pinecone(api_key="YOUR_PINECONE_API_KEY")

# Liệt kê tất cả các index mà API key này có quyền truy cập
indexes = pc.list_indexes()

print(f"Tìm thấy {len(indexes)} index:")
for idx in indexes:
    print(f"- Tên: {idx.name} | Host: {idx.host}")

Nếu index my-index của bạn không có trong danh sách in ra, API key của bạn chắc chắn đang trỏ đến sai project.

Cách khắc phục triệt để### 1. Sử dụng biến môi trườngViệc viết cứng (hardcode) các chuỗi ký tự rất dễ dẫn đến lỗi đánh máy. Hãy sử dụng tệp .env để quản lý cấu hình. Điều này đảm bảo script cục bộ sử dụng chính xác các chuỗi ký tự như môi trường production. Nếu bạn đang dùng SDK v3.0.0 trở lên, cấu hình của bạn nên như sau:

import os
from pinecone import Pinecone
from dotenv import load_dotenv

load_dotenv()

pc = Pinecone(api_key=os.getenv("PINECONE_API_KEY"))
index_name = os.getenv("PINECONE_INDEX_NAME")

# Kiểm tra phòng vệ: xác minh sự tồn tại trước khi kết nối
active_names = [i.name for i in pc.list_indexes()]
if index_name not in active_names:
    print(f"Lỗi: không tìm thấy {index_name}. Hiện có: {active_names}")
else:
    index = pc.Index(index_name)

2. Chỉ định trực tiếp Host URLĐôi khi việc tự động tra cứu của SDK thất bại do sự cố mạng cục bộ hoặc DNS. Bạn có thể bỏ qua bước tra cứu bằng cách cung cấp đầy đủ URL host tìm thấy trong dashboard Pinecone. Nó thường là một chuỗi dài kết thúc bằng pinecone.io.

# Kết nối thủ công qua host (hữu ích khi gỡ lỗi serverless)
index = pc.Index(name="my-index", host="https://my-index-xyz.svc.us-east-1-aws.pinecone.io")

3. Xác minh sự cô lập của ProjectĐăng nhập vào Pinecone Console. Kiểm tra bộ chọn project ở góc trên bên trái. Nếu bạn có nhiều project, hãy kiểm tra từng cái. Rất phổ biến trường hợp tạo index trong project tên là "Default" nhưng lại tạo API key cho project "Test-Project". Key không thể dùng chéo giữa các project.

Xác minh cuối cùngKhi bạn nghĩ mình đã khắc phục xong kết nối, hãy chạy một bước kiểm tra thông số nhanh. Nếu lệnh này trả về dữ liệu, kết nối của bạn đã ổn định:

# Xác minh kết nối và kiểm tra số lượng vector
stats = index.describe_index_stats()
print(f"Kết nối thành công. Tổng số vector: {stats['total_vector_count']}")

Nếu describe_index_stats() trả về một đối tượng JSON với kích thước (dimensions) và số lượng, bạn đã sẵn sàng. Nếu vẫn thấy lỗi, hãy đảm bảo rằng index của bạn không bị xóa do hết hạn dùng thử.