OpenAI Python SDK 串接 AIXHUB
建立隔離 Python 環境、呼叫 AIXHUB Responses、檢查完整物件、安全處理串流，並管理 SDK 升級。
OpenAI Python SDK 可透過含版本的 Base URL https://api.aixhub.org/v1 呼叫 AIXHUB。本指南會明確傳入 AIXHUB 金鑰與 Base URL，避免既有官方 OpenAI 環境設定悄悄生效。
前置條件
- 目前
openai套件支援的 Python 3。Windows 執行py -3 --version；macOS/Linux 執行python3 --version。 - 只供此應用程式使用的專用 AIXHUB API 金鑰。
- 從模型路由複製的完整 Responses 相容模型 ID；範例用
panel-openai-model-id作為明顯替代值。 - 不含其他虛擬環境，也沒有名為
openai.py檔案的可丟棄專案目錄。
AIXHUB_API_KEY 與 AIXHUB_MODEL 是本站文件約定，不是 SDK 自動讀取的變數；程式會明確傳入 OpenAI(...) 與 responses.create(...)。
操作步驟
建立並啟用虛擬環境
Windows PowerShell：
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install openai
python -m pip show openai若本機政策禁止啟用，不要降低整台電腦的安全政策。請直接執行 .\.venv\Scripts\python.exe -m pip ... 與 .\.venv\Scripts\python.exe aixhub_openai.py。
macOS 或 Linux：
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install openai
python -m pip show openai排錯或升級前先記錄已安裝版本。不可使用 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-openai-model-id"PowerShell：
$secureKey = Read-Host "AIXHUB API key" -AsSecureString
$env:AIXHUB_API_KEY = [System.Net.NetworkCredential]::new("", $secureKey).Password
$env:AIXHUB_MODEL = "panel-openai-model-id"請把模型替代值換成面板複製的完整 ID。正式環境應由核准的伺服器端秘密管理服務注入金鑰，不使用互動式 Shell。
建立完整非串流程式
建立 aixhub_openai.py：
import os
import sys
import openai
from openai import OpenAI
def main() -> None:
client = OpenAI(
api_key=os.environ["AIXHUB_API_KEY"],
base_url="https://api.aixhub.org/v1",
max_retries=0,
timeout=60.0,
)
try:
response = client.responses.create(
model=os.environ["AIXHUB_MODEL"],
input="Reply with OK only.",
)
print(response.output_text)
print(response.model_dump_json(indent=2))
request_id = getattr(response, "_request_id", None)
if request_id:
print(f"request_id={request_id}")
if response.status != "completed":
raise RuntimeError(f"response ended with status={response.status}")
except openai.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 的 output_text 便利屬性會組合文字輸出；model_dump_json() 可檢查完整型別化回應。處理原始物件時，不可假設 output[0] 一定是文字訊息。
使用作用中虛擬環境的 Python 執行：
python aixhub_openai.py串流文字並要求終止事件
建立 aixhub_openai_stream.py：
import os
import sys
import openai
from openai import OpenAI
client = OpenAI(
api_key=os.environ["AIXHUB_API_KEY"],
base_url="https://api.aixhub.org/v1",
max_retries=0,
timeout=60.0,
)
final_response = None
try:
with client.responses.with_streaming_response.create(
model=os.environ["AIXHUB_MODEL"],
input="Reply with OK only.",
stream=True,
) as raw_response:
if raw_response.request_id:
print(f"request_id={raw_response.request_id}", file=sys.stderr)
events = raw_response.parse()
for event in events:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
elif event.type == "response.completed":
final_response = event.response
elif event.type in {"response.failed", "response.incomplete", "error"}:
raise RuntimeError(f"stream ended with {event.type}")
print()
if final_response is None:
raise RuntimeError("stream closed without a terminal response.completed event")
print(final_response.model_dump_json(indent=2))
except openai.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_openai_stream.py。部分文字與 HTTP 200 都不代表成功；只有 response.completed 才算成功。重新送出失敗、不完整、逾時或斷線的生成前，先查看用量記錄。
驗證
非串流程式第一行與串流組合文字都應是：
OK另外確認：
- 完整回應的
status是completed，並包含預期模型 ID。 - 只有 SDK 實際提供 request ID 時才記錄，不可自行產生。
- AIXHUB 用量在相同時間出現所選模型與成功狀態。
- 串流確實到達
response.completed，不是收到部分文字後直接斷線。
常見問題
ModuleNotFoundError或沒有responses屬性： 確認python -m pip show openai指向作用中.venv；重新命名本機openai.py，再於該環境升級套件。- 401／
AuthenticationError： 確認程式收到AIXHUB_API_KEY，而且base_url指向 AIXHUB。不可使用官方 OpenAI 帳號 Token。 - 403／
PermissionDeniedError： 檢查金鑰分組、訂閱與餘額；INSUFFICIENT_BALANCE是 403。 - 404／
NotFoundError： 保持base_url="https://api.aixhub.org/v1"，由 SDK 附加/responses；重新複製模型並確認支援 Responses。 - 429／
RateLimitError： 遵守實際Retry-After、降低並行數，並使用有限嘗試額度。 APIConnectionError或逾時： 檢查 Proxy、TLS、DNS 與網路。結果可能不明；再次傳送可計費生成前先查看用量。APIStatusError： 實際提供時記錄status_code與request_id。分享回應內容前先遮蔽，因為其中可能含應用程式資料。output_text空白： 檢查完整物件並依type遍歷輸出；文字訊息前可能有推理、工具呼叫或非文字內容。
驗證程式設定 max_retries=0，讓一次命令只產生一次可觀察 SDK 嘗試。正式環境只能指定一個重試負責層：啟用 SDK 重試時，應用程式不可再包一層重試迴圈；由應用程式負責時則保持 max_retries=0。所有層合計最多三次總嘗試，且包含原始請求；例如 SDK max_retries=2 已用完整個額度。逾時、5xx、失敗或不完整串流、斷線等結果不明時，要先查看用量；除非應用程式接受重複輸出與費用，否則不可重送。請參考錯誤代碼。
下一步
將產生的物件與原始 OpenAI Responses 參考比較，或在移入服務前重新閱讀認證與 Base URL。
升級與復原
升級前記錄可用套件集合：
python -m pip freeze > requirements.before-aixhub-sdk.txt
python -m pip show openai只在虛擬環境中升級，再重新執行兩個程式與用量驗證：
python -m pip install --upgrade openai
python -m pip check
python aixhub_openai.py若升級破壞原本已驗證的串接，請在相同虛擬環境重裝先前記錄版本後再測試：
python -m pip install "openai==<recorded-version>"不再於此環境使用套件時：
python -m pip uninstall openai
deactivate只有虛擬環境或範例程式完全為本指南建立，而且沒有必須保留的工作時才能刪除。確認沒有部署服務仍使用後，再撤銷專用 AIXHUB 金鑰。
安全注意事項
-
金鑰不可放入原始碼、提交到 Git 的
.env、Traceback、Notebook、遙測與完整 HTTP 記錄。 -
輸入後，
AIXHUB_API_KEY會以明文存在目前的 Shell 環境。避免傳給子行程，部署服務要使用正式秘密管理服務。 -
完整回應可能含提示內容、生成內容、工具參數與中繼資料；記錄或分享前先遮蔽。
-
為可計費生成明確設定重試、逾時與重複結果政策。
-
在本指南開啟的可丟棄 Shell 中，測試結束後清除暫存狀態：
unset AIXHUB_API_KEY AIXHUB_MODELRemove-Item Env:AIXHUB_API_KEY, Env:AIXHUB_MODEL -ErrorAction SilentlyContinue Remove-Variable secureKey -ErrorAction SilentlyContinue若任一環境變數在本指南前已存在，不可在該 Shell 執行清理命令。請改用另一個終端機測試，或從獲准的秘密來源還原原始值。
官方資料
最後核對：2026-07-14