> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinecone

> Kết nối một project Pinecone để agent kiểm tra index và namespace, tìm kiếm bản ghi và upsert qua Approvals của bạn

Kết nối một project Pinecone để agent CloudThinker liệt kê index, đọc số bản ghi theo namespace, tìm kiếm bản ghi bằng văn bản, và tạo index hoặc upsert bản ghi qua [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) của bạn. Kết nối đăng nhập bằng một **project API key** Pinecone, nên chỉ truy cập được index của đúng project đó.

## Điều kiện tiên quyết

* Một project Pinecone chứa các index bạn muốn agent truy cập.
* Quyền tạo API key trong project đó.
* Để tìm kiếm và ghi: index được tạo với **integrated embedding**, nghĩa là Pinecone tự sinh vector từ văn bản bằng một embedding model được host sẵn. Index xây từ vector bạn tự embed có thể được liệt kê và mô tả, nhưng không thể tìm kiếm hay ghi qua kết nối này. Không chắc mình có loại nào? Hãy kết nối, rồi hỏi agent index nào dùng integrated embedding.

## Thiết lập

**1. Tạo API key**

Trong Pinecone console, mở project mà agent cần đọc và vào **API keys**. Nhấn **Create API key** và đặt tên `cloudthinker`. Nếu gói của bạn hiển thị tùy chọn quyền, đặt control plane và data plane ở chế độ chỉ đọc, trừ khi agent cần ghi (xem [Quyền yêu cầu](#quyền-yêu-cầu)). Nhấn **Create key**.

**2. Sao chép key**

Sao chép key ngay. Pinecone chỉ hiển thị key một lần.

**3. Thêm kết nối trong CloudThinker**

Trên thanh bên, nhấn **More → Workspace settings → Connections**, rồi trên tab **Builtin Connections** chọn **Pinecone**. Dán key vào **PINECONE\_API\_KEY** và nhấn **Connect**.

**Trạng thái thành công:** kết nối hiển thị trạng thái **Connected**. Chạy prompt xác minh bên dưới để xác nhận key hoạt động với project của bạn.

## Chi tiết kết nối

| Trường | Bắt buộc | Mô tả | Ví dụ |
| - | - | - | - |
| **Alias** | Không | Tên ngắn cho kết nối này. Agent và [Rules](https://docs.cloudthinker.io/vi/guide/approvals/rules.md) dùng tên này để phân biệt các kết nối | `search-prod` |
| **Description** | Không | Project này chứa gì. Agent đọc mô tả để chọn đúng kết nối, nên hãy viết cụ thể | `Production search indexes for the docs site` |
| **PINECONE\_API\_KEY** | Có | Nhãn trường trong form CloudThinker. Dán API key của một project Pinecone | `<your-api-key>` |

Để truy cập index trong project khác, thêm key từ project đó thành một kết nối riêng.

## Quyền yêu cầu

| Bạn muốn agent | Key cần |
| - | - |
| Liệt kê và mô tả index | Control plane read |
| Đọc thống kê index và tìm kiếm bản ghi | Data plane read |
| Tạo index | Control plane write |
| Upsert bản ghi | Data plane write |

> [!TIP]
>
> Bắt đầu với key chỉ đọc nếu gói Pinecone cho phép giới hạn quyền API key. Một số gói chỉ có quyền truy cập đầy đủ; khi đó, chính phê duyệt trong CloudThinker sẽ chặn các thao tác ghi không mong muốn.

## Khả năng của agent

| Khả năng | Agent có thể làm gì | Được Approvals kiểm tra |
| - | - | - |
| **Danh mục index** | Liệt kê index, đọc cấu hình, số chiều, số bản ghi và namespace của từng index | Không |
| **Tìm kiếm** | Tìm kiếm một index integrated embedding bằng văn bản, hoặc tìm trên nhiều index cùng lúc với kết quả đã loại trùng và xếp hạng lại | Không |
| **Rerank** | Xếp hạng lại danh sách tài liệu bạn cung cấp, không cần index | Không |
| **Tạo index** | Tạo một index integrated embedding mới | Có |
| **Upsert bản ghi** | Thêm hoặc cập nhật bản ghi trong một namespace của index integrated embedding | Có |

Kết nối không thể xóa bản ghi, namespace hay index.

Thao tác ghi tuân theo Rules và chế độ [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) của workspace, như mọi thay đổi khác. Khi thao tác cần người phê duyệt, agent hiển thị trước chính xác tên index, namespace, embedding model và các bản ghi. Với index mới, hãy nêu cloud và region bạn muốn trong prompt, hoặc từ chối và nói rõ cần dùng cloud và region nào.

Mọi thay đổi do agent thực hiện đều đi qua [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) của workspace trước. Ở chế độ mặc định **Auto · Rules + AI · Ask me**, AI judgment có thể cho một thay đổi an toàn chạy mà không cần hỏi. Allow Rule cũng vậy, sau khi CloudThinker bật [Rule enforcement](https://docs.cloudthinker.io/vi/guide/approvals/rules.md#khắc-phục-sự-cố) cho workspace của bạn. Chọn **Manual** nếu bạn muốn tự phê duyệt mọi thay đổi.

> [!WARNING]
>
> Tạo serverless index, embedding bản ghi khi upsert hoặc tìm kiếm, và rerank đều được tính vào mức sử dụng và hóa đơn Pinecone của bạn. Hãy nêu cloud và region trong prompt trước khi agent tạo index.

### Xác minh kết nối

```text theme={null}
List my Pinecone indexes with each one's record count and namespaces
```

Kết quả mong đợi: mọi index trong project kèm số chiều, số bản ghi và các namespace như `__default__`.

### Ví dụ prompt

```text theme={null}
Which Pinecone indexes use integrated embedding, and how many records does each namespace hold?
Search the docs-search index for "refund policy" and show the five best matches with scores
Upsert these three FAQ records into the faq namespace of docs-search
```

## Khắc phục sự cố

> **Mọi yêu cầu đều lỗi 401**
>
> Key bị thiếu, gõ sai, đã bị xóa hoặc thuộc project khác. Tạo key mới trong đúng project, rồi sửa kết nối và dán key vào **PINECONE\_API\_KEY**.

> **Tìm kiếm không trả về gì, hoặc một index không tìm kiếm được**
>
> Index không dùng integrated embedding, hoặc namespace sai. Hỏi agent index nào dùng integrated embedding. Nếu bạn không nêu namespace, bản ghi thường nằm trong `__default__`.

> **Agent không tìm thấy index nào**
>
> Project chưa có index, hoặc key thuộc project khác. Kiểm tra project trong Pinecone console, hoặc yêu cầu agent tạo một index integrated embedding.

> **Thao tác ghi thất bại sau khi tôi đã phê duyệt**
>
> Key không có quyền ghi, hoặc index đích không dùng integrated embedding. Kiểm tra quyền của key trong Pinecone console.

> **Yêu cầu trả về 429**
>
> Pinecone đang giới hạn tốc độ của project. Đợi một lát rồi hỏi lại, và tránh chạy nhiều tìm kiếm lớn cùng lúc.

## Bảo mật

* **Quyền tối thiểu** — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
* **Chỉ đọc theo mặc định** — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
* **Xoay vòng thông tin xác thực** — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
* **Thu hồi khi bàn giao** — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.

- **Một project cho mỗi key**: tạo key trong đúng project mà agent cần truy cập, và xóa key trong Pinecone khi bạn gỡ kết nối.
- **Chỉ đọc khi gói cho phép**: key không có quyền ghi không thể tạo index hay upsert, dù thao tác có được phê duyệt hay không.

## Liên quan

> **[Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md)**
>
> Quyết định thao tác tạo index và upsert nào được chạy, chờ người duyệt hoặc bị từ chối.

> **[Tổng quan kết nối](https://docs.cloudthinker.io/vi/guide/connections/overview.md)**
>
> Xoay vòng key, đặt môi trường và xem mọi kết nối.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.