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

# Sử dụng Pi với CometAPI

> Sử dụng hướng dẫn này để cấu hình Pi với CometAPI bằng cách thiết lập base URL, API key và các tùy chọn model hoặc provider.

[Pi](https://github.com/earendil-works/pi) là dự án Pi Agent Harness. Gói `@earendil-works/pi-coding-agent` của nó cung cấp một CLI coding agent tương tác với các quy trình làm việc file, shell, edit, write, session, print, JSON, RPC và SDK. Pi có thể tải các provider tùy chỉnh từ `~/.pi/agent/models.json`, vì vậy bạn có thể thêm CometAPI dưới dạng các mục OpenAI-compatible provider mà không cần thay đổi mã nguồn của Pi.

Tài liệu tham khảo chính thức:

* [Kho lưu trữ Pi](https://github.com/earendil-works/pi)
* [Bắt đầu nhanh với Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md)
* [Các provider của Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md)
* [Các model tùy chỉnh của Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Cách dùng Pi CLI](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<Note>
  Khả dụng của model thay đổi theo thời gian. Hãy thay `your-model-id` bằng một model ID khả dụng từ [trang Models của CometAPI](/vi/overview/models).
</Note>

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

* Node.js `>=22.19.0`
* npm
* Một tài khoản CometAPI có API key đang hoạt động từ [bảng điều khiển](https://www.cometapi.com/console/token)
* Pi được cài đặt từ gói npm chính thức

## Hiểu về quyền runtime

Pi chạy với các quyền của người dùng và tiến trình khởi chạy nó. Hãy khởi động Pi trong thư mục dự án mà bạn muốn nó làm việc, duy trì một phương án hoàn tác như git, và sử dụng container hoặc sandbox nếu bạn cần ranh giới chặt chẽ hơn cho filesystem, process, network hoặc credentials.

## Cấu hình provider

<Steps>
  <Step title="Cài đặt Pi">
    Cài đặt Pi toàn cục bằng npm:

    ```bash theme={null}
    npm install -g --ignore-scripts @earendil-works/pi-coding-agent
    ```

    Xác nhận rằng CLI khả dụng:

    ```bash theme={null}
    pi --version
    ```
  </Step>

  <Step title="Thiết lập API key CometAPI của bạn">
    Lưu API key CometAPI của bạn trong biến môi trường `COMETAPI_KEY`:

    ```bash theme={null}
    read -rsp "CometAPI API key: " COMETAPI_KEY
    printf '\n'
    export COMETAPI_KEY
    ```

    Thêm lệnh export vào shell profile của bạn nếu muốn nó được giữ lại giữa các phiên terminal. Không commit API key vào hệ thống quản lý phiên bản.
  </Step>

  <Step title="Thêm provider CometAPI vào models.json">
    Tạo `~/.pi/agent/models.json` nếu chưa tồn tại. Nếu tệp đã chứa các provider, hãy gộp các mục `cometapi-responses` và `cometapi-chat` vào object `providers` hiện có:

    ```json theme={null}
    {
      "providers": {
        "cometapi-responses": {
          "name": "CometAPI Responses",
          "baseUrl": "https://api.cometapi.com/v1",
          "api": "openai-responses",
          "apiKey": "$COMETAPI_KEY",
          "models": [
            {
              "id": "your-model-id",
              "name": "CometAPI Responses model"
            }
          ]
        },
        "cometapi-chat": {
          "name": "CometAPI Chat Completions",
          "baseUrl": "https://api.cometapi.com/v1",
          "api": "openai-completions",
          "apiKey": "$COMETAPI_KEY",
          "models": [
            {
              "id": "your-model-id",
              "name": "CometAPI Chat model"
            }
          ]
        }
      }
    }
    ```

    Sử dụng `cometapi-responses` cho các model hoặc workflow yêu cầu OpenAI Responses API. Sử dụng `cometapi-chat` cho các model tương thích với OpenAI Chat Completions. Pi phân giải `$COMETAPI_KEY` tại thời điểm gửi request. Giữ API key trong môi trường của bạn hoặc trong quy trình quản lý secrets riêng của bạn.
  </Step>

  <Step title="Xác minh cả hai provider">
    Liệt kê các model mà Pi có thể nhìn thấy cho provider Responses:

    ```bash theme={null}
    pi --list-models cometapi-responses
    ```

    Chạy một prompt one-shot ngắn với provider Responses:

    ```bash theme={null}
    pi --provider cometapi-responses --model your-model-id -p "Reply with one short sentence confirming the Responses connection."
    ```

    Liệt kê các model mà Pi có thể nhìn thấy cho provider Chat Completions:

    ```bash theme={null}
    pi --list-models cometapi-chat
    ```

    Chạy một prompt one-shot ngắn với provider Chat Completions:

    ```bash theme={null}
    pi --provider cometapi-chat --model your-model-id -p "Reply with one short sentence confirming the Chat Completions connection."
    ```

    Để sử dụng tương tác, khởi động Pi trong project của bạn và chọn provider CometAPI cùng model bằng `/model`. Nếu bạn chỉnh sửa `models.json` trong một phiên tương tác, hãy mở lại `/model` để Pi tải lại các mục model tùy chỉnh.
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion title="Pi không hiển thị model CometAPI">
    Xác nhận rằng `~/.pi/agent/models.json` là JSON hợp lệ và mỗi mục provider nằm bên trong đối tượng `providers` ở cấp cao nhất. Chạy `pi --list-models cometapi-responses` hoặc `pi --list-models cometapi-chat` sau khi lưu tệp.
  </Accordion>

  <Accordion title="Pi báo rằng không có API key khả dụng">
    Xác nhận rằng `COMETAPI_KEY` được thiết lập trong cùng phiên shell dùng để khởi chạy Pi. Nếu bạn sử dụng hồ sơ shell, hãy mở terminal mới hoặc nạp hồ sơ đó trước khi chạy Pi.
  </Accordion>

  <Accordion title="Yêu cầu thất bại do base URL">
    Sử dụng `https://api.cometapi.com/v1` làm `baseUrl` trong `models.json`. Không trỏ Pi tới URL dashboard hoặc bỏ hậu tố `/v1` đối với các route tương thích OpenAI.
  </Accordion>

  <Accordion title="Pi thất bại trước khi gửi yêu cầu model">
    Kiểm tra phiên bản Node.js của bạn bằng `node --version`. Gói Pi yêu cầu Node.js `>=22.19.0`.
  </Accordion>

  <Accordion title="Model hoạt động trên một route nhưng không hoạt động trên route còn lại">
    Sử dụng mục provider có trường `api` khớp với route mà model của bạn hỗ trợ. `openai-responses` sử dụng Responses API, trong khi `openai-completions` sử dụng Chat Completions.
  </Accordion>

  <Accordion title="Pi có nhiều quyền truy cập hơn dự kiến">
    Pi chạy với quyền của người dùng và tiến trình đã khởi chạy nó. Hãy chạy Pi trong container hoặc sandbox khi bạn cần ranh giới chặt chẽ hơn đối với tệp, tiến trình, truy cập mạng hoặc thông tin xác thực.
  </Accordion>
</AccordionGroup>

## Tài nguyên liên quan

* [Bắt đầu nhanh với CometAPI](/vi/overview/quick-start)
* [Trang Models của CometAPI](/vi/overview/models)
* [Các model tùy chỉnh của Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)
* [Cách sử dụng Pi CLI](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/usage.md)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/pi#howto",
        "name": "Sử dụng Pi với CometAPI",
        "description": "Sử dụng hướng dẫn này để cấu hình Pi với CometAPI bằng cách thiết lập base URL, API key và các tùy chọn model hoặc provider.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-1",
            "position": 1,
            "name": "Cài đặt Pi",
            "text": "Hoàn thành bước Cài đặt Pi trong hướng dẫn Sử dụng Pi với CometAPI."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-2",
            "position": 2,
            "name": "Thiết lập CometAPI API key của bạn",
            "text": "Lưu CometAPI API key của bạn trong biến môi trường hoặc trường cài đặt mà integration sử dụng."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-3",
            "position": 3,
            "name": "Thêm các provider CometAPI vào models.json",
            "text": "Hoàn thành bước Thêm các provider CometAPI vào models.json trong hướng dẫn Sử dụng Pi với CometAPI."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/pi#step-4",
            "position": 4,
            "name": "Xác minh cả hai provider",
            "text": "Hoàn thành bước Xác minh cả hai provider trong hướng dẫn Sử dụng Pi với CometAPI."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "Tài liệu CometAPI",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Tích hợp",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "Sử dụng Pi với CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/pi"
          }
        ]
      }
    ]
    }
    `}
</script>