> ## 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.

# Braintrust

> Kết nối Braintrust để CloudThinker có thể so sánh điểm của experiment, đọc monitor view và kiểm tra cài đặt project bằng một API key.

Kết nối tổ chức Braintrust của bạn và hỏi [CloudThinker](https://docs.cloudthinker.io/vi/guide/agents/overview.md) một experiment đạt điểm thế nào so với baseline, một monitor view đã lưu hiển thị gì, hoặc một project được cấu hình ra sao. Kết nối dùng một **API key** Braintrust và chỉ đọc: CloudThinker có thể xem, không bao giờ thay đổi.

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

* Tổ chức Braintrust trên data plane US của Braintrust. CloudThinker luôn kết nối tới `api.braintrust.dev`, nên data plane EU và các bản triển khai Braintrust tự host không được hỗ trợ.
* Quyền tạo API key trong tổ chức đó.
* Vai trò **Admin** trong workspace CloudThinker, cần để thêm kết nối. Xem [Vai trò](https://docs.cloudthinker.io/vi/guide/security/roles.md).

> [!TIP]
>
> API key của Braintrust mang quyền của người dùng đã tạo nó và không thể giới hạn thấp hơn người dùng đó, nên hãy tạo key từ một tài khoản chỉ cần đọc. Nếu gói Braintrust của bạn có permission group, hãy đưa tài khoản đó vào nhóm **Viewers**, nhóm này cấp quyền đọc các project của tổ chức. Key do owner tạo vẫn hoạt động, nhưng mang quyền owner.

## Thiết lập

**1. Mở API keys trong Braintrust**

Đăng nhập Braintrust bằng tài khoản chỉ đọc bạn đã chọn ở trên và vào **Settings → API keys**.

**2. Tạo key**

Nhấn **+ API key**, đặt tên `cloudthinker` và chọn thời hạn. Thời hạn không thể đổi sau, nên hãy đặt lời nhắc trên lịch để xoay vòng key trước ngày đó (xem [Bảo mật](#bảo-mật)). Nhấn **Create**.

**3. Sao chép key**

Sao chép key ngay. Braintrust chỉ hiển thị key một lần. Nếu mất key, hãy tạo key mới.

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

Mở **More → Workspace settings → Connections**, giữ nguyên tab **Builtin Connections** và chọn **Braintrust**. Dán key vào **BRAINTRUST\_API\_KEY** rồi nhấn **Connect**.

**Trạng thái thành công:** thẻ Braintrust hiển thị **Connected**.

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

| Trường | Bắt buộc | Mô tả | Ví dụ |
| - | - | - | - |
| **BRAINTRUST\_API\_KEY** | Có | API key từ **Settings → API keys** trong tổ chức Braintrust của bạn | `<your-api-key>` |

Không cần nhập data plane hay URL: CloudThinker luôn gọi `api.braintrust.dev`.

## Quyền yêu cầu

Phạm vi của key chính là phạm vi của người tạo. Braintrust không thể giới hạn key thấp hơn tài khoản đã tạo nó, nên tài khoản bạn chọn chính là ranh giới quyền.

> [!TIP]
>
> Tạo key từ một tài khoản có quyền đọc các project mà CloudThinker cần thấy, và không hơn. Ngay cả với key có quyền rộng hơn, CloudThinker cũng chỉ chạy sáu thao tác đọc bên dưới.

## Khả năng của agent

CloudThinker chỉ cho phép đúng sáu thao tác Braintrust trên kết nối này. Mọi thứ khác Braintrust cung cấp đều bị chặn.

| Khả năng | Bạn nhận được gì |
| - | - |
| **Đối tượng gần đây** | Tối đa 10 project, experiment, dataset, prompt hoặc function gần đây thuộc một loại |
| **Tóm tắt experiment** | Điểm và số liệu của một experiment, có thể so sánh với một experiment baseline |
| **Tra cứu đối tượng** | Xác định một tên, ID hoặc URL Braintrust trỏ tới đối tượng nào |
| **Liên kết chia sẻ** | Liên kết Braintrust tới một đối tượng đã xác định, sẵn sàng dán vào ticket hoặc chat |
| **Monitor view** | Một monitor view đã lưu và các biểu đồ của nó, theo tên chính xác |
| **Cài đặt project** | Cài đặt của một project |

CloudThinker báo cáo tên và số lượng. CloudThinker chỉ hiển thị ID đối tượng khi bạn yêu cầu.

> [!WARNING]
>
> CloudThinker không thể chạy SQL trên log của bạn, liệt kê automation, duyệt tất cả monitor view, hoặc tạo, chỉnh sửa hay chạy bất cứ thứ gì trong Braintrust. Hãy làm những việc đó trực tiếp trong Braintrust.

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

```text theme={null}
List my 5 most recent Braintrust projects and report their names only
```

**Trạng thái thành công:** bạn nhận được danh sách ngắn tên project khớp với những gì bạn thấy trong Braintrust. Lỗi 401 nghĩa là key sai hoặc đã hết hạn; xem [Khắc phục sự cố](#khắc-phục-sự-cố).

### Ví dụ prompt

Dùng tên chính xác từ Braintrust. CloudThinker tra cứu đúng đối tượng bạn nêu tên, không đoán.

```text theme={null}
How did the support-bot-v3 experiment score compared with the support-bot-v2 experiment?
Show the saved monitor view called production-latency and list its charts
What are the settings of the support-bot project?
```

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

> **Mọi yêu cầu đều thất bại với 401 Unauthorized**
>
> Braintrust không chấp nhận key. Key có thể bị gõ sai, đã bị xóa hoặc đã hết hạn. Tạo key mới, rồi mở **More → Workspace settings → Connections**, chọn **Braintrust** và thay giá trị.

> **403 Forbidden, hoặc không tìm thấy project hay experiment**
>
> Key chỉ thấy những gì tài khoản của người tạo thấy. Kiểm tra quyền truy cập của tài khoản đó vào project hoặc experiment trong Braintrust, và kiểm tra tên chính xác bạn đã dùng.

> **Đã chạy tốt nhiều tháng, rồi mọi yêu cầu bắt đầu thất bại**
>
> Key đã hết hạn. Key Braintrust không thể gia hạn, nên hãy tạo key mới và cập nhật kết nối. Đặt lời nhắc trên lịch trước lần hết hạn tiếp theo.

> **Tổ chức của tôi dùng data plane EU hoặc tự host Braintrust**
>
> Kết nối này chỉ giao tiếp với `api.braintrust.dev`. Kết nối không thể truy cập data plane EU hoặc các bản triển khai tự host.

> **CloudThinker từ chối chạy truy vấn hoặc thay đổi dữ liệu**
>
> Đó là thiết kế có chủ đích. Kết nối chỉ cho phép sáu thao tác đọc được liệt kê trong [Khả năng của agent](#khả-năng-của-agent).

## 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.

- **Phạm vi tài khoản**: key hoạt động với tư cách người tạo, nên hãy tạo key từ tài khoản chỉ có quyền đọc.
- **Thời hạn**: chọn thời hạn bạn sẽ theo dõi, và xoay vòng key trước khi hết hạn.

## Liên quan

> **[Langfuse](https://docs.cloudthinker.io/vi/guide/connections/langfuse.md)**
>
> Thêm trace và prompt LLM từ Langfuse

> **[LangSmith](https://docs.cloudthinker.io/vi/guide/connections/langsmith.md)**
>
> Thêm run, dataset và experiment LLM từ LangSmith

> **[Lệnh và cú pháp prompt](https://docs.cloudthinker.io/vi/guide/commands.md)**
>
> Hướng câu hỏi tới một kết nối bằng #


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