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

# Langfuse

> Kết nối Langfuse với CloudThinker để điều tra LLM trace, gỡ lỗi hội thoại, xem xét điểm đánh giá và kiểm tra prompt

Kết nối project Langfuse của bạn để cho phép các agent CloudThinker điều tra LLM trace, gỡ lỗi hội thoại, xem xét điểm đánh giá và dataset, cũng như kiểm tra các phiên bản prompt trên toàn bộ stack quan sát của bạn. Langfuse xác thực bằng **cặp API key theo phạm vi project** (public key và secret key) đối chiếu với Langfuse host của bạn — cùng một cài đặt hoạt động được cho cả Langfuse Cloud và các instance tự lưu trữ.

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

* Một **project Langfuse Cloud hoặc tự lưu trữ** mà bạn muốn điều tra.
* Một **cặp API key theo phạm vi project** (public key và secret key) từ project đó.
* **URL Langfuse host** của bạn (`https://cloud.langfuse.com` cho EU, `https://us.cloud.langfuse.com` cho US, hoặc tên miền tự lưu trữ của bạn).

<Info>
  API key Langfuse được giới hạn phạm vi theo một project duy nhất. Tạo cặp key trong project mà CloudThinker cần tiếp cận, và sử dụng cặp key riêng dành cho CloudThinker để dễ kiểm tra và thu hồi.
</Info>

## Thiết lập

<Steps>
  <Step title="Mở Langfuse">
    Đăng nhập vào Langfuse và chọn project bạn muốn CloudThinker điều tra.
  </Step>

  <Step title="Tạo cặp API key">
    Vào **Project → Settings → API Keys** và nhấn **Create new API keys**. Langfuse tạo:

    * Một **Public Key** (có tiền tố `pk-lf-`)
    * Một **Secret Key** (có tiền tố `sk-lf-`)

    Sao chép secret key ngay lập tức — nó chỉ hiển thị một lần và không thể lấy lại sau đó.
  </Step>

  <Step title="Thêm kết nối trong CloudThinker">
    Điều hướng đến **Connections → Langfuse** và nhập:

    * **Host**: URL cơ sở Langfuse của bạn, ví dụ `https://cloud.langfuse.com` (chỉ URL cơ sở, không có path)
    * **Public Key**: key `pk-lf-` vừa tạo
    * **Secret Key**: key `sk-lf-` vừa tạo

    Nhấn **Connect**. CloudThinker xác minh thông tin xác thực và hiển thị trạng thái **Connected**.
  </Step>
</Steps>

<Warning>
  Sao chép secret key ngay sau khi tạo. Langfuse chỉ hiển thị một lần, vì vậy bạn cần tạo cặp key mới nếu mất.
</Warning>

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

| Trường                    | Mô tả                                                                | Ví dụ                        |
| ------------------------- | -------------------------------------------------------------------- | ---------------------------- |
| **LANGFUSE\_HOST**        | URL cơ sở của instance Langfuse — EU cloud, US cloud hoặc tự lưu trữ | `https://cloud.langfuse.com` |
| **LANGFUSE\_PUBLIC\_KEY** | Public key theo phạm vi project                                      | `pk-lf-...`                  |
| **LANGFUSE\_SECRET\_KEY** | Secret key theo phạm vi project                                      | `sk-lf-...`                  |

## Quyền yêu cầu

API key Langfuse kế thừa quyền truy cập của project mà chúng thuộc về. CloudThinker sử dụng cặp key cho các luồng công việc đọc và điều tra trên các trace, observation, số liệu, điểm số, dataset, hàng đợi chú thích, bình luận và prompt.

<Tip>
  Tuân theo nguyên tắc ít quyền nhất: giới hạn phạm vi cặp key theo project duy nhất mà CloudThinker cần điều tra, và tách biệt khỏi các key dùng bởi SDK hoặc tích hợp khác để có thể xoay vòng hoặc thu hồi độc lập.
</Tip>

## Khả năng của agent

Sau khi kết nối, các agent có thể điều tra dữ liệu quan sát LLM trên toàn bộ project Langfuse của bạn.

| Khả năng               | Mô tả                                                                     |
| ---------------------- | ------------------------------------------------------------------------- |
| **Trace**              | Tìm kiếm và kiểm tra trace, tương quan lỗi, độ trễ và sử dụng model       |
| **Observation**        | Đi sâu vào span, generation và sự kiện trong một trace                    |
| **Số liệu**            | Truy vấn số liệu sử dụng, độ trễ và chi phí trong một khoảng thời gian    |
| **Điểm số**            | Xem xét điểm đánh giá và tín hiệu chất lượng                              |
| **Dataset**            | Kiểm tra dataset dùng để đánh giá và kiểm thử                             |
| **Hàng đợi chú thích** | Xem xét hàng đợi chú thích và các item của chúng                          |
| **Bình luận**          | Đọc bình luận được để lại trên trace và observation                       |
| **Prompt**             | Liệt kê phiên bản prompt, nhãn và các thay đổi gần đây để kiểm tra prompt |

<Note>
  URL chat CloudThinker mang một `conversationId` ánh xạ đến `sessionId` trong Langfuse. Yêu cầu agent phân tích URL chat và nó sẽ giải quyết session qua Langfuse thay vì lấy URL dưới dạng trang web.
</Note>

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

```text theme={null}
@alex investigate recent Langfuse traces and summarize errors, latency, and model usage
```

### Ví dụ lệnh

```text theme={null}
@alex investigate recent failed Langfuse traces for production conversations, correlate errors and latency, and #recommend likely fixes
@alex inspect this CloudThinker chat URL by mapping its conversationId to a Langfuse session and summarize tool calls, model usage, and failures
@alex list active Langfuse prompts, versions, and labels, and #report prompts tied to degraded scores
```

Các truy vấn trace và số liệu được giới hạn theo thời gian, vì vậy hãy đề cập đến khoảng thời gian (ví dụ "một giờ qua") để kết quả luôn tập trung.

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

<Accordion title="Kết nối thất bại với 401 Unauthorized">
  Xác minh public key và secret key đúng và chưa bị xoay vòng hoặc xóa. Xác nhận cả hai key thuộc **cùng** một project Langfuse và được sao chép không có khoảng trắng thừa.
</Accordion>

<Accordion title="Host hoặc region sai">
  Dữ liệu được tách biệt theo region, vì vậy cặp key chỉ hoạt động với host mà nó được tạo. Kiểm tra **LANGFUSE\_HOST** khớp với URL bạn đăng nhập, ví dụ `https://cloud.langfuse.com` cho EU hoặc `https://us.cloud.langfuse.com` cho US.
</Accordion>

<Accordion title="Mọi yêu cầu đều trả về 404">
  **LANGFUSE\_HOST** có hậu tố path thừa. Đặt thành URL cơ sở, không có đường dẫn thừa.
</Accordion>

<Accordion title="Tìm kiếm không trả về kết quả">
  Tìm kiếm trace và số liệu cần khoảng thời gian. Yêu cầu agent dùng cửa sổ gần đây (ví dụ một giờ qua) và mở rộng chỉ khi cần. Xác nhận project đang nhận trace tích cực từ ứng dụng của bạn.
</Accordion>

<Accordion title="URL chat không được phân tích như session">
  Yêu cầu agent trích xuất `conversationId` và ánh xạ nó đến `sessionId` trong Langfuse thay vì lấy URL trực tiếp.
</Accordion>

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

- **Cặp key theo phạm vi project** — sử dụng cặp key giới hạn theo project duy nhất mà CloudThinker điều tra; tạo cặp riêng cho CloudThinker để dễ kiểm tra và thu hồi độc lập.
- **Host đúng** — khớp host với region nơi project tồn tại để tránh lỗi cross-region.

## Liên quan

<CardGroup cols={2}>
  <Card title="Kết nối SigNoz" icon="https://mintcdn.com/cloudthinker/CGWam0VVP8R5KVLk/images/icons/signoz.svg?fit=max&auto=format&n=CGWam0VVP8R5KVLk&q=85&s=d08abadb07adcc41c8812b59483344e3" href="/vi/guide/connections/signoz" width="24" height="24" data-path="images/icons/signoz.svg">
    Log, số liệu, trace và dashboard
  </Card>

  <Card title="Kết nối Datadog" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/datadog.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=e8382167f2a1eb1e00971b5f4d703d48" href="/vi/guide/connections/datadog" width="24" height="24" data-path="images/icons/datadog.svg">
    Tìm kiếm log, số liệu và giám sát
  </Card>
</CardGroup>