Anthropic Python SDK 串接 AIXHUB

建立隔離 Python 環境、呼叫 AIXHUB Messages、檢查內容區塊、安全處理串流，並管理 SDK 升級。

Anthropic Python SDK 會在 AIXHUB 根 Base URL https://api.aixhub.org 後附加 /v1/messages。本指南會明確傳入 AIXHUB 金鑰與 Base URL，避免官方 Anthropic 憑證或 Profile 悄悄取代設定。

前置條件

目前 anthropic 套件支援的 Python 3。Windows 執行 py -3 --version；macOS/Linux 執行 python3 --version。
只供此應用程式使用的專用 AIXHUB API 金鑰。
從模型路由複製的完整 Anthropic Messages 相容模型 ID；範例用 panel-anthropic-model-id 作為明顯替代值。
不含其他虛擬環境，也沒有名為 anthropic.py 檔案的可丟棄專案目錄。

AIXHUB_API_KEY 與 AIXHUB_MODEL 是本站文件約定，不是 SDK 自動讀取的變數；程式會明確傳入 Anthropic(...) 與 messages.create(...)。

操作步驟

建立並啟用虛擬環境

Windows PowerShell：

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install anthropic
python -m pip show anthropic

若本機政策禁止啟用，不要降低整台電腦的安全政策。請直接執行 .\.venv\Scripts\python.exe -m pip ... 與 .\.venv\Scripts\python.exe aixhub_anthropic.py。

macOS 或 Linux：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install anthropic
python -m pip show anthropic

排錯或升級前先記錄已安裝版本。不可使用 sudo pip，也不要安裝到系統 Python。

設定不會進入歷程的暫存憑證

請開啟原本沒有 AIXHUB_API_KEY 與 AIXHUB_MODEL 的可丟棄 Shell，避免測試覆寫其他工作流程的值。

Bash：

read -rsp "AIXHUB API key: " AIXHUB_API_KEY && echo
export AIXHUB_API_KEY
export AIXHUB_MODEL="panel-anthropic-model-id"

PowerShell：

$secureKey = Read-Host "AIXHUB API key" -AsSecureString
$env:AIXHUB_API_KEY = [System.Net.NetworkCredential]::new("", $secureKey).Password
$env:AIXHUB_MODEL = "panel-anthropic-model-id"

請把模型替代值換成面板複製的完整 ID。正式環境應由核准的伺服器端秘密管理服務注入金鑰，不使用互動式 Shell。

建立完整非串流程式

建立 aixhub_anthropic.py：

import os
import sys

import anthropic
from anthropic import Anthropic


def main() -> None:
    client = Anthropic(
        api_key=os.environ["AIXHUB_API_KEY"],
        base_url="https://api.aixhub.org",
        max_retries=0,
        timeout=60.0,
    )
    try:
        message = client.messages.create(
            model=os.environ["AIXHUB_MODEL"],
            max_tokens=16,
            messages=[
                {"role": "user", "content": "Reply with OK only."},
            ],
        )

        text = "".join(
            block.text for block in message.content if block.type == "text"
        )
        print(text)
        print(message.model_dump_json(indent=2))

        request_id = getattr(message, "_request_id", None)
        if request_id:
            print(f"request_id={request_id}")

        if message.stop_reason != "end_turn":
            raise RuntimeError(f"message ended with stop_reason={message.stop_reason}")
    except anthropic.APIStatusError as exc:
        print(f"status_code={exc.status_code}", file=sys.stderr)
        if exc.request_id:
            print(f"request_id={exc.request_id}", file=sys.stderr)
        raise
    finally:
        client.close()


if __name__ == "__main__":
    main()

SDK 會回傳型別化內容區塊。必須以 type == "text" 篩選，不可假設 message.content[0] 是文字。model_dump_json() 可檢查完整訊息、停止原因與用量。

使用作用中虛擬環境的 Python 執行：

python aixhub_anthropic.py

串流文字並要求最終訊息

建立 aixhub_anthropic_stream.py：

import os
import sys

import anthropic
from anthropic import Anthropic


client = Anthropic(
    api_key=os.environ["AIXHUB_API_KEY"],
    base_url="https://api.aixhub.org",
    max_retries=0,
    timeout=60.0,
)

try:
    with client.messages.stream(
        model=os.environ["AIXHUB_MODEL"],
        max_tokens=16,
        messages=[
            {"role": "user", "content": "Reply with OK only."},
        ],
    ) as stream:
        if stream.request_id:
            print(f"request_id={stream.request_id}", file=sys.stderr)
        for text in stream.text_stream:
            print(text, end="", flush=True)
        final_message = stream.get_final_message()

    print()
    print(final_message.model_dump_json(indent=2))
    if final_message.stop_reason != "end_turn":
        raise RuntimeError(
            f"stream ended with stop_reason={final_message.stop_reason}"
        )
except anthropic.APIStatusError as exc:
    print(f"status_code={exc.status_code}", file=sys.stderr)
    if exc.request_id:
        print(f"request_id={exc.request_id}", file=sys.stderr)
    raise
finally:
    client.close()

執行 python aixhub_anthropic_stream.py。必須在 Context Manager 內消耗完整串流後，才能使用 get_final_message()。部分文字與 HTTP 200 都不代表成功；error 事件、斷線或沒有最終訊息都不是成功。重新送出不明確生成前先查看用量記錄。

驗證

非串流程式第一行與串流組合文字都應是：

OK

另外確認：

完整訊息含有文字區塊 OK、預期模型 ID，而且 stop_reason 是 end_turn。
只有 SDK 實際提供 request ID 時才記錄，不可自行產生。
AIXHUB 用量在相同時間出現所選模型與成功狀態。
串流消耗所有事件後產生最終訊息。

Anthropic SDK 在型別化文字區塊回傳 OK，最終訊息正常結束，而且 AIXHUB 留下相符 Messages 請求。

常見問題

ModuleNotFoundError 或匯入失敗： 確認 python -m pip show anthropic 指向作用中 .venv；重新命名本機 anthropic.py，再於該環境升級套件。
401／AuthenticationError： 確認明確傳入的 AIXHUB_API_KEY 仍有效。本程式不可依賴 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或官方 Profile。
403／PermissionDeniedError： 檢查金鑰分組、訂閱與餘額；INSUFFICIENT_BALANCE 是 403。
404／NotFoundError： 保持 base_url="https://api.aixhub.org"，由 SDK 附加 /v1/messages；重新複製模型並確認支援 Messages。
413／RequestTooLargeError： 縮小提示內容或附件後再重試。
429／RateLimitError： 遵守實際 Retry-After、降低並行數，並使用有限嘗試額度。
APIConnectionError 或逾時： 檢查 Proxy、TLS、DNS 與網路。結果可能不明；再次傳送可計費生成前先查看用量。
APIStatusError： 實際提供時記錄 status_code 與 request_id，分享回應內容前先遮蔽。
content[0] 沒有文字： 本指南會依類型篩選內容區塊；請檢查完整訊息是否為工具使用或其他區塊類型。

驗證程式設定 max_retries=0，讓一次命令只產生一次可觀察 SDK 嘗試。正式環境只能指定一個重試負責層：啟用 SDK 重試時，應用程式不可再包一層重試迴圈；由應用程式負責時則保持 max_retries=0。所有層合計最多三次總嘗試，且包含原始請求；例如 SDK max_retries=2 已用完整個額度。逾時、5xx、串流錯誤或斷線等結果不明時，要先查看用量；除非應用程式接受重複輸出與費用，否則不可重送。請參考錯誤代碼。

下一步

將型別化訊息與原始 Anthropic Messages 參考比較，或依 Claude Code設定持續維護的終端機流程。

升級與復原

升級前記錄可用套件集合：

python -m pip freeze > requirements.before-aixhub-sdk.txt
python -m pip show anthropic

只在虛擬環境中升級，再重新執行兩個程式與用量驗證：

python -m pip install --upgrade anthropic
python -m pip check
python aixhub_anthropic.py

若升級破壞原本已驗證的串接，請在相同虛擬環境重裝先前記錄版本後再測試：

python -m pip install "anthropic==<recorded-version>"

不再於此環境使用套件時：

python -m pip uninstall anthropic
deactivate

只有虛擬環境或範例程式完全為本指南建立，而且沒有必須保留的工作時才能刪除。確認沒有部署服務仍使用後，再撤銷專用 AIXHUB 金鑰。

安全注意事項

金鑰不可放入原始碼、提交的 .env、Traceback、Notebook、遙測與完整 HTTP 記錄。
輸入後，AIXHUB_API_KEY 會以明文存在目前的 Shell 環境。避免傳給子行程，部署服務要使用正式秘密管理服務。
完整訊息可能含提示內容、生成內容、工具輸入與中繼資料；記錄或分享前先遮蔽。
為可計費生成明確設定重試、逾時與重複結果政策。
在本指南開啟的可丟棄 Shell 中，測試結束後清除暫存狀態：
```
unset AIXHUB_API_KEY AIXHUB_MODEL
```
```
Remove-Item Env:AIXHUB_API_KEY, Env:AIXHUB_MODEL -ErrorAction SilentlyContinue
Remove-Variable secureKey -ErrorAction SilentlyContinue
```
若任一環境變數在本指南前已存在，不可在該 Shell 執行清理命令。請改用另一個終端機測試，或從獲准的秘密來源還原原始值。

官方資料

最後核對：2026-07-14

Anthropic Python SDK 串接 AIXHUB

本頁目錄