Providers

Pi hỗ trợ các nhà cung cấp dựa trên đăng ký thông qua các nhà cung cấp OAuth và API key thông qua các biến môi trường hoặc tệp xác thực. Danh mục tích hợp đi kèm với pi; các nhà cung cấp đã định cấu hình có thể làm mới các danh mục mới hơn và lưu chúng vào bộ nhớ đệm trong ~/.pi/agent/models-store.json để sử dụng ngoại tuyến.

• Subscriptions
• API Keys
• Auth File
• Cloud Providers
• llama.cpp
• Custom Providers
• Resolution Order

Sử dụng /login ở chế độ tương tác, sau đó chọn nhà cung cấp:

• ChatGPT Plus/Pro (Codex)
• Claude Pro/Max
• GitHub Copilot
• xAI (Grok/X subscription)
• OpenRouter (OAuth-minted API key billed from OpenRouter credits)
• Radius

Sử dụng /logout để xóa thông tin xác thực. Mã thông báo được lưu trữ trong ~/.pi/agent/auth.json và tự động làm mới khi hết hạn. Thay vào đó, OpenRouter tạo ra một API key do người dùng kiểm soát và không tự động hết hạn.

• Yêu cầu đăng ký ChatGPT Plus hoặc Pro
• Được xác nhận chính thức bởi OpenAI: Codex for OSS

Xác thực đăng ký Anthropic đang hoạt động cho tài khoản Claude Pro/Max. Mức sử dụng từ công cụ bên thứ ba được trừ vào extra usage và tính phí theo token, không tính vào giới hạn của gói Claude.

• Nhấn Enter để truy cập github.com hoặc nhập miền GitHub Enterprise Server của bạn
• Nếu bạn nhận được "model not supported", hãy bật trong VS Code: Copilot Chat → model selector → chọn model → "Enable"

• Chạy /login xai, sau đó chọn Sử dụng đăng ký
• XAI_API_KEY vẫn có sẵn thông qua Sử dụng API key

• Chạy /login openrouter, sau đó chọn Đăng nhập bằng OpenRouter để mở luồng ủy quyền OpenRouter PKCE
• Ủy quyền tạo OpenRouter API key do người dùng kiểm soát được tính phí từ tín dụng OpenRouter của bạn
• Trên các máy từ xa/không có đầu (ví dụ: trên SSH), trình duyệt không thể truy cập lệnh gọi lại vòng lặp; thay vào đó hãy dán URL chuyển hướng cuối cùng (hoặc mã ủy quyền) vào lời nhắc đăng nhập
• OPENROUTER_API_KEY vẫn có sẵn thông qua Sử dụng API key

Radius là một gateway pi-messages động. /login radius lưu OAuth token trong auth.json; catalog của gateway được làm mới độc lập và cache trong models-store.json. Có thể khai báo các Radius gateway tùy chỉnh trong models.json với "oauth": "radius" và gateway baseUrl.

Sử dụng /login ở chế độ tương tác và chọn nhà cung cấp để lưu trữ API key trong auth.json hoặc đặt thông tin xác thực thông qua biến môi trường:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Tham chiếu cho các biến môi trường và khóa auth.json: const envMap trong packages/ai/src/env-api-keys.ts.

Lưu trữ thông tin xác thực trong ~/.pi/agent/auth.json:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "ant-ling": { "type": "api_key", "key": "..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." },
  "nvidia": { "type": "api_key", "key": "nvapi-..." },
  "google": { "type": "api_key", "key": "..." },
  "opencode": { "type": "api_key", "key": "..." },
  "opencode-go": { "type": "api_key", "key": "..." },
  "together": { "type": "api_key", "key": "..." },
  "qwen-token-plan":  { "type": "api_key", "key": "sk-sp-..." },
  "qwen-token-plan-individual": { "type": "api_key", "key": "sk-sp-..." },
  "qwen-token-plan-cn": { "type": "api_key", "key": "sk-sp-..." },
  "xiaomi": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-cn":  { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-sgp": { "type": "api_key", "key": "..." }
}

qwen-token-plan-individual sử dụng cùng điểm cuối quốc tế và QWEN_TOKEN_PLAN_API_KEY như qwen-token-plan, nhưng giới hạn bộ chọn ở các mô hình được ghi lại cho đăng ký Cá nhân. Hiện có nhà cung cấp giữ danh mục rộng hơn để có khả năng tương thích ngược. Khi sử dụng auth.json, hãy lưu trữ thông tin xác thực theo nhà cung cấp bạn chọn; một biến môi trường được chia sẻ bởi cả hai nhà cung cấp quốc tế.

Tệp được tạo với quyền 0600 (chỉ người dùng đọc/ghi). Thông tin xác thực tệp xác thực được ưu tiên hơn các biến môi trường.

Thông tin xác thực API key cũng có thể bao gồm các giá trị môi trường theo phạm vi provider. Các giá trị này được dùng trước biến môi trường của tiến trình khi phân giải khóa thông tin xác thực, header provider/model và cấu hình provider như ID tài khoản Cloudflare, cài đặt Azure OpenAI, dự án/vị trí Vertex, cài đặt Bedrock, PI_CACHE_RETENTION và HTTP_PROXY/HTTPS_PROXY.

{
  "cloudflare-ai-gateway": {
    "type": "api_key",
    "key": "$CLOUDFLARE_API_KEY",
    "env": {
      "CLOUDFLARE_API_KEY": "...",
      "CLOUDFLARE_ACCOUNT_ID": "account-id",
      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
    }
  }
}

Sử dụng điều này khi pi nên sử dụng các cài đặt nhà cung cấp khác với môi trường shell dự án.

Trường key hỗ trợ thực thi lệnh, nội suy môi trường và chữ:

• Lệnh Shell: "!command" khi bắt đầu thực thi toàn bộ giá trị dưới dạng lệnh và sử dụng stdout (được lưu trong bộ nhớ đệm trong suốt thời gian xử lý)

  { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
  { "type": "api_key", "key": "!op read 'op://vault/item/credential'" }

• Nội suy môi trường: "$ENV_VAR" hoặc "${ENV_VAR}" sử dụng giá trị của biến được đặt tên. Nội suy hoạt động bên trong các chữ lớn hơn.

  { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
  { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }

  $FOO_BAR là biến FOO_BAR; sử dụng ${FOO}_BAR khi BAR là văn bản chữ. Thiếu biến môi trường làm cho giá trị không được giải quyết.
• Escape: "$" phát ra literal "
  quot;; "$!" phát ra literal "!" mà không kích hoạt thực thi lệnh.

  { "type": "api_key", "key": "$literal-dollar-prefix" }
  { "type": "api_key", "key": "$!literal-bang-prefix" }

• Giá trị bằng chữ: Được sử dụng trực tiếp. Các chuỗi viết hoa đơn giản như MY_API_KEY là chữ; sử dụng $MY_API_KEY cho các biến môi trường.

  { "type": "api_key", "key": "sk-ant-..." }
  { "type": "api_key", "key": "public" }

Thông tin xác thực OAuth cũng được lưu trữ tại đây sau /login và được quản lý tự động.

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
# also supported: https://your-resource.cognitiveservices.azure.com
# also supported: https://your-resource.openai.azure.com
# root endpoints are auto-normalized to /openai/v1
# or use resource name instead of base URL
export AZURE_OPENAI_RESOURCE_NAME=your-resource

# Optional
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o

Sử dụng /login amazon-bedrock để lưu API key Bedrock, hoặc cấu hình một trong các nguồn thông tin xác thực AWS có sẵn trong môi trường dưới đây:

# Option 1: AWS Profile
export AWS_PROFILE=your-profile

# Option 2: IAM Keys
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# Option 3: Bearer Token
export AWS_BEARER_TOKEN_BEDROCK=...

# Optional region (defaults to us-east-1)
export AWS_REGION=us-west-2

Đồng thời hỗ trợ các vai trò nhiệm vụ ECS (AWS_CONTAINER_CREDENTIALS_*) và IRSA (AWS_WEB_IDENTITY_TOKEN_FILE).

pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

Bộ nhớ đệm nhắc nhở được bật tự động cho các mô hình Claude có ID chứa tên mô hình có thể nhận dạng được (mô hình cơ sở và cấu hình suy luận do hệ thống xác định). Đối với cấu hình suy luận ứng dụng (có ARN không chứa tên kiểu máy), hãy đặt AWS_BEDROCK_FORCE_CACHE=1 để bật điểm bộ đệm:

export AWS_BEDROCK_FORCE_CACHE=1
pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123

Nếu bạn đang kết nối với proxy Bedrock API, có thể sử dụng các biến môi trường sau:

# Set the URL for the Bedrock proxy (standard AWS SDK env var)
export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock

# Set if your proxy does not require authentication
export AWS_BEDROCK_SKIP_AUTH=1

# Set if your proxy only supports HTTP/1.1
export AWS_BEDROCK_FORCE_HTTP1=1

CLOUDFLARE_API_KEY có thể được đặt qua /login. ID tài khoản và sên cổng có thể được đặt làm biến môi trường hoặc trong đối tượng env của thông tin xác thực trong auth.json.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
pi --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"

Các tuyến đến OpenAI, Anthropic và Workers AI thông qua Cloudflare AI Gateway. AI công nhân sử dụng ID mô hình hợp nhất API (/compat) và tiền tố (workers-ai/@cf/...). OpenAI sử dụng lộ trình chuyển tiếp OpenAI (/openai) với ID mô hình OpenAI gốc như gpt-5.1. Anthropic sử dụng lộ trình chuyển tiếp Anthropic (/anthropic) với ID mô hình Anthropic gốc chẳng hạn như claude-sonnet-4-5.

Xác thực Cổng AI sử dụng CLOUDFLARE_API_KEY làm cf-aig-authorization. Xác thực ngược dòng có thể là một trong:

Để sử dụng pi thông thường, hãy ưu tiên thanh toán thống nhất hoặc BYOK được lưu trữ. BYOK nội tuyến yêu cầu định cấu hình tiêu đề Authorization ngược dòng bổ sung cho nhà cung cấp Cloudflare AI Gateway, chẳng hạn như thông qua ghi đè mô hình/nhà cung cấp models.json.

CLOUDFLARE_API_KEY có thể được đặt qua /login. CLOUDFLARE_ACCOUNT_ID có thể được đặt làm biến môi trường hoặc trong đối tượng env của thông tin xác thực trong auth.json.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
pi --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"

Pi tự động đặt x-session-affinity để được giảm giá prefix caching.

Sử dụng thông tin xác thực mặc định của ứng dụng:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

Hoặc đặt GOOGLE_APPLICATION_CREDENTIALS thành tệp khóa tài khoản dịch vụ.

Pi hỗ trợ máy chủ bộ định tuyến llama.cpp. Định cấu hình nó bằng /login llama.cpp, quản lý các mô hình đã tải bằng /llama và chọn một mô hình đã tải bằng /model.

Xem llama.cpp để biết cách thiết lập máy chủ, bố cục thư mục mô hình, biến môi trường và cách sử dụng lệnh.

Qua models.json: Thêm Ollama, LM Studio, vLLM hoặc bất kỳ nhà cung cấp nào hỗ trợ API tương thích (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). Xem models.md.

Thông qua tiện ích mở rộng: Đối với các nhà cung cấp cần triển khai API tùy chỉnh hoặc luồng OAuth, hãy tạo tiện ích mở rộng. Xem custom-provider.md và examples/extensions/custom-provider-gitlab-duo.

Khi giải quyết thông tin xác thực cho nhà cung cấp:

1. cờ CLI --api-key
2. auth.json mục nhập (API key hoặc OAuth mã thông báo)
3. Biến môi trường
4. Khóa nhà cung cấp tùy chỉnh từ models.json