AIProxyServer - Hướng dẫn

Bắt đầu

1. Khởi chạy ứng dụng

Mở AIProxyServer. Trong lần khởi chạy đầu tiên, proxy sẽ tự động chạy và lắng nghe trên cổng 8421 của máy cục bộ. Cửa sổ chính hiển thị ba phần:

• Máy chủ proxy — trạng thái hiện tại, URL cơ sở và nút để khởi động hoặc dừng trình lắng nghe
• Bearer Token — công tắc xác thực tùy chọn và phần hiển thị token
• Nhà cung cấp — mọi nhà cung cấp AI đám mây được hỗ trợ, kèm theo Đặt khóa API một nút trên mỗi hàng

2. Thêm khóa API đầu tiên

1. Chọn một nhà cung cấp bất kỳ trong danh sách Nhà cung cấp (ví dụ: OpenAI (ChatGPT))
2. Nhấp vào Lấy khóa API để mở bảng điều khiển của nhà cung cấp trong trình duyệt, sau đó tạo hoặc sao chép một khóa
3. Nhấp vào Đặt khóa API trên cùng hàng rồi dán giá trị vào hộp thoại
4. Nhấp vào Lưu. Nhãn trạng thái sẽ chuyển thành Đã cấu hình với màu xanh lục

3. Kết nối ứng dụng khách

Trỏ ứng dụng khách tương thích với OpenAI đến proxy. URL cơ sở là http://localhost:8421/<provider>/v1. Phân đoạn nhà cung cấp sẽ xác định dịch vụ đám mây nhận yêu cầu.

# Example: OpenAI Python SDK pointed at the proxy
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Ứng dụng khách không bao giờ nhìn thấy khóa thật. AIProxyServer đính kèm thông tin xác thực của dịch vụ nguồn khi chuyển tiếp yêu cầu.

Tổng quan giao diện

Bảng Máy chủ proxy

Bảng Bearer Token

• Yêu cầu xác thực bằng Bearer Token — hộp kiểm bật hoặc tắt xác thực. Mặc định tắt để sử dụng cục bộ thuận tiện.
• Trường token — phần chỉ đọc hiển thị token hiện tại. Token được che bằng dấu chấm; hãy dùng Sao chép để lấy token.
• Tạo lại — tạo một token ngẫu nhiên mới. Các ứng dụng khách hiện có phải được cập nhật bằng giá trị mới.

Bảng Nhà cung cấp

Mỗi nhà cung cấp đám mây được hỗ trợ có một hàng. Mỗi hàng hiển thị:

• Tên hiển thị (ví dụ: Claude (Anthropic))
• Trạng thái cấu hình — màu xanh lục Đã cấu hình khi đã lưu khóa API, màu xám Chưa cấu hình trong các trường hợp còn lại
• Đường dẫn URL mà ứng dụng khách sử dụng, ví dụ: /anthropic/v1/chat/completions
• Đặt khóa API — mở hộp thoại để nhập thông tin xác thực
• Lấy khóa API — mở bảng điều khiển của nhà cung cấp trong trình duyệt

Các nhà cung cấp được hỗ trợ

Ứng dụng tích hợp mười một dịch vụ AI đám mây. Hầu hết sử dụng sẵn định dạng OpenAI Chat Completions và được proxy nguyên trạng. Ba dịch vụ (Anthropic, Gemini, ERNIE) dùng giao thức riêng; AIProxyServer chuyển đổi yêu cầu và phản hồi tức thời để ứng dụng khách luôn chỉ nhận cấu trúc OpenAI.

Lưu ý riêng theo nhà cung cấp

• Azure OpenAI — dán toàn bộ điểm cuối triển khai vào trường URL cơ sở của điểm cuối , ví dụ: https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy tự động nối thêm /chat/completions?api-version=2024-02-01 .
• ERNIE — Baidu Qianfan sử dụng OAuth, vì vậy cần cả API Key và Secret Key . AIProxyServer sẽ yêu cầu và lưu vào bộ nhớ đệm các access token ở chế độ nền.
• Gemini — xác thực thông qua tham số truy vấn URL; proxy sẽ tự thêm tham số này. Hạn ngạch theo phút của gói miễn phí vẫn được áp dụng.

Tài liệu tham khảo API

Điểm cuối

Truyền phát

Khi ứng dụng khách gửi "stream": true, proxy phản hồi bằng Server-Sent Events theo định dạng OpenAI:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

Luồng gốc của Anthropic và Gemini được chuyển đổi sang cấu trúc này để mọi ứng dụng khách có thể dùng chung một trình phân tích.

Tiêu đề xác thực

Khi Yêu cầu xác thực bằng Bearer Token được bật, hãy gửi token từ cửa sổ chính trong mọi yêu cầu:

Authorization: Bearer <token-shown-in-app>

Cài đặt

Mở cửa sổ Cài đặt bằng biểu tượng bánh răng trên thanh công cụ phía dưới.

Ví dụ cho ứng dụng khách

cURL

# OpenAI (passthrough)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Claude via the same OpenAI shape
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # ignored when Bearer Token is off
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// Using any OpenAI-compatible Dart client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // unused when Bearer Token is off
);

Mẹo

• Hãy để Bearer Token ở trạng thái tắt khi phát triển cục bộ; bật ngay khi bạn cho phép truy cập LAN.
• Dùng URL cơ sở riêng cho từng nhà cung cấp trong mã ứng dụng khách để có thể chuyển nhà cung cấp chỉ bằng cách thay đổi một hằng số.
• Proxy tự động khởi động, nhưng bạn có thể tạm dừng từ cửa sổ chính nếu xảy ra xung đột cổng.
• Nếu gói miễn phí của nhà cung cấp giới hạn tần suất, thông báo lỗi từ dịch vụ nguồn sẽ được chuyển tiếp nguyên văn. Ứng dụng khách không bị che giấu bất kỳ logic thử lại nào.
• Điểm cuối /v1/providers hữu ích để xác định trong thời gian chạy những nhà cung cấp nào đã được cấu hình.

Khắc phục sự cố

Proxy không khởi động

• Một tiến trình khác có thể đang sử dụng cổng 8421. Hãy đổi cổng trong Cài đặt rồi khởi động lại proxy.
• Kiểm tra nhật ký hệ thống để xem thông báo lỗi hiển thị lúc khởi động.

Yêu cầu trả về 401 Unauthorized

• Yêu cầu Bearer Token đang bật nhưng ứng dụng khách không gửi giá trị khớp trong tiêu đề Authorization: Bearer ... .
• Khóa API riêng của nhà cung cấp có thể không hợp lệ — lỗi từ dịch vụ nguồn được chuyển tiếp, vì vậy hãy kiểm tra nội dung thông báo.

Yêu cầu trả về "API key is not configured"

• Mở danh sách Nhà cung cấp và nhấp vào Đặt khóa API cho nhà cung cấp liên quan.
• Với ERNIE, phải điền cả API Key và Secret Key. Với Azure OpenAI, cũng cần có URL cơ sở của điểm cuối.

Thiết bị di động không thể truy cập proxy

• Bật Cho phép truy cập LAN trong Cài đặt.
• Dùng địa chỉ IP LAN hiển thị trong trường URL cơ sở, không dùng localhost.
• Đảm bảo cả hai thiết bị cùng kết nối một mạng Wi-Fi và tường lửa cho phép kết nối đến trên cổng proxy.

Phản hồi truyền phát đến cùng một lúc

• Đảm bảo ứng dụng khách gửi "stream": true trong phần thân JSON.
• Một số thư viện HTTP mặc định lưu SSE vào bộ đệm — hãy tắt bộ đệm phản hồi ở phía ứng dụng khách.

Quyền riêng tư

• Khóa API được mã hóa bằng Fernet và lưu tại ~/Library/Application Support/AIProxyServer/credentials.enc. Khóa mã hóa trong master.key có quyền 0600.
• Khi được bật, Bearer Token cũng chỉ được lưu trong kho mã hóa và không bao giờ được ghi vào tệp cài đặt thông thường.
• Proxy chỉ chuyển tiếp yêu cầu đến những nhà cung cấp bạn đã cấu hình rõ ràng. Ứng dụng không thực hiện cuộc gọi ra ngoài nào khác.
• Không đo từ xa, không phân tích dữ liệu, không báo cáo sự cố.
• Liên kết mạng mặc định chỉ là 127.0.0.1 . Việc cho phép truy cập qua LAN là tùy chọn chủ động.
• Nội dung cuộc trò chuyện không được lưu. AIProxyServer chuyển tiếp dữ liệu rồi quên ngay lập tức.