Skip to content
AI Blog

通義千問 API 與阿里雲百煉入門

最後更新：2026-09-17· 17 分鐘閱讀

🚀 快速通道

  • Qwen Max：點擊直達↗
  • 多模型對話工作台：開啟鏡像↗
  • 官方 Qwen：chat.qwen.ai ↗

通義千問 API 與阿里雲百煉入門

更新時間：2026-09-17。端點、模型名、價格與限流以 阿里雲百煉文件 與 百煉控制台 當天頁面為準；下文用占位符，避免寫入易過期的具體型號與單價。

導讀

「通義千問 API」「阿里雲百煉」「Qwen API 入門」對應的是把 Qwen 模型接到網站、腳本、客服機器人或內部工具——入口在 阿里雲百煉（Model Studio），而不是通義千問 App 的聊天帳號。可上線的接入不只是「請求 200」，還要管：金鑰不進瀏覽器、逾時與重試、結構化校驗、用量與預算、日誌脫敏。 網頁聊天與 API 的配額、模型列表、帳單不要預設當成同一套。

這篇解決什麼問題？

  • 分清百煉 API 與通義千問聊天產品的帳號/計費邊界
  • 完成阿里雲帳號、百煉開通與 API Key 準備
  • 用環境變數安全發起第一次請求（含 OpenAI 相容思路）
  • 設計逾時、重試、錯誤分類與成本控制
  • 上線前過一遍安全清單

百煉 vs 聊天產品：先搞清邊界

維度通義千問聊天產品阿里雲百煉 API
典型入口通義 App、官網對話頁百煉控制台
主要用途人工試用、輕量對話伺服器端整合、自動化、批次任務
鑑權方式登入態 / 產品帳號API Key（DashScope 等，以文件為準）
計費產品套餐或免費額度按呼叫量 / 資源包，獨立帳單
模型列表以聊天介面可選為準以控制台與 API 文件列表為準

日常試用可走 Qwen Max 對話 或 多模型對話工作台；產品整合必須走伺服器端 API，並在百煉控制台單獨開通與儲值。

開通前準備：帳戶、Key、計費

  1. 登入 阿里雲帳號，進入 百煉控制台。
  2. 依控制台引導完成 百煉服務開通 與 計費 / 資源包 設定；設定預算或用量告警（若提供）。
  3. 在「API-KEY 管理」或文件所示入口建立 Key：立即複製到密碼管理器或金鑰服務；頁面可能不再完整顯示。
  4. 替 Key 打用途標籤（如 dev-chat / prod-summarizer），便於外洩後定向吊销。
  5. 在 Model Studio 文件 確認當前 base URL、鑑權頭、模型 ID 列表——不要從過期部落格抄。

若你已有通義千問 App 帳號，不代表 API Key 已就緒；兩者權限與帳單獨立，需分別在控制台核對。

環境變數：金鑰只放伺服器端

# Linux / macOS 範例（本地開發）
export DASHSCOPE_API_KEY="your-secret-here"
# Windows PowerShell（僅當前工作階段；正式環境請用平台 Secret）
$env:DASHSCOPE_API_KEY = "your-secret-here"

環境變數名以官方文件為準（常見為 DASHSCOPE_API_KEY）；此處僅為範例占位。

硬性規則：

  • Key 永遠不要寫進前端、行動 App、公開倉庫、截圖、ISSUE
  • 用 process.env / 部署平台 Secret / 雲端金鑰管理器
  • 不同環境（dev / staging / prod）使用不同 Key
  • 懷疑外洩 → 控制台立刻吊销並輪換

第一個請求（占位符，請對照文件替換）

阿里雲百煉提供 OpenAI 相容 呼叫方式（具體路徑與欄位以文件「OpenAI 相容」章節為準）。以下範例展示請求形狀；請將 OFFICIAL_API_ENDPOINT 與 MODEL_ID_FROM_DOCS 替換為文件中的當前值。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="OFFICIAL_API_ENDPOINT",  # 從官方文件複製，如相容模式 base URL
)

resp = client.chat.completions.create(
    model="MODEL_ID_FROM_DOCS",  # 如 qwen-max、qwen-plus 等，以控制台為準
    messages=[
        {"role": "user", "content": "用三點解釋什麼是冪等性"}
    ],
    timeout=60,
)
print(resp.choices[0].message.content)

若不用 OpenAI SDK，也可用 requests 依文件 REST 格式 POST；鑑權頭名稱（如 Authorization: Bearer 或 X-DashScope-Api-Key）以當日文件為準。

跑通後立刻檢查：回應裡的用量欄位（若有）、延遲、以及你是否誤把 Key 打進了日誌。

模型 ID 與版本注意

  • 控制台顯示的模型名（如 Qwen Max、Qwen Plus、Qwen Turbo）與 API 的 model 字串可能不同，每次整合前回查文件。
  • 新模型或預覽版可能需單獨開通；未開通時常見 403 或「模型不存在」類錯誤。
  • 禁止把內測、限時或帶日期的臨時 ID 寫死進正式環境設定；應配回退到穩定型號。
  • 多模態、工具呼叫、JSON 模式等能力因模型而異，以文件能力矩陣為準。

可複製業務提示（放在 messages 裡）

你是內部知識助手。只根據提供的 context 回答。
若 context 不足，回答「資料中未提及」並列出缺失資訊。
不得編造連結、法規條文或數據。
context:
"""
[脫敏段落]
"""
問題：[使用者問題]

串流輸出說明

互動式 UI 通常需要 streaming，讓使用者先看到部分 token。百煉文件中有串流（SSE）說明；事件格式與客戶端解析以官方章節為準。注意：

  • 串流同樣要設總體逾時與閒置逾時
  • 中途斷開要可恢復或明確失敗，避免前端無限轉圈
  • 不要在瀏覽器持有 Key 去做「直連串流」；由後端代發

可靠性設計（上線必做）

  1. 逾時：連線逾時 + 讀取逾時；避免請求掛死占滿執行緒
  2. 重試：僅對 429 / 5xx / 網路閃斷 做有限次指數退避；401/403/400 不要盲重試
  3. 冪等：寫入操作帶業務冪等鍵，防止重試重複下單類副作用
  4. 校驗：要求 JSON 時做 schema 校驗；失敗則安全降級或有限次「修復請求」
  5. 隔離：單使用者 QPS 限額、全局限流、熔斷
  6. 可觀測：記錄 request_id（若回傳）、模型名、耗時、token、錯誤碼；不記錄原始身分證/銀行卡/完整對話隱私
  7. 版本：system prompt、模型名、溫度類參數納入設定版本管理

錯誤處理對照表

情況典型表現處理
認證失敗401 / 金鑰無效檢查環境變數與 Key 狀態；不重試
權限/未開通403 / 模型未授權查控制台開通狀態與帳戶餘額
參數錯誤400 / 模型名無效對照文件修正 model 與欄位
限流429退避、排隊、降並發、申請提額
伺服器錯誤5xx有上限重試 + 告警
逾時client timeout縮短上下文、降 max tokens、非同步化
輸出不合格JSON 壞掉校驗失敗路徑 + 有限次重試

成本控制

  • 限制輸入長度與最大輸出；長歷史做摘要或截斷
  • 對相同請求做快取（注意個人化與隱私邊界）
  • 按路由選模型：簡單分類用輕量檔，複雜推理再升 Max 檔（名稱以文件為準）
  • 記錄每日 token 與費用；設定預算告警
  • 批次處理盡量非高峰；避免無意義的多輪「再想想」循環

不要在教學或程式註解裡寫死「某模型每百萬 token 價格」——以 百煉定價頁 即時資料為準。

安全清單（上線前必查）

  • Key 僅存在於伺服器端環境變數或金鑰管理器
  • 倉庫、CI 日誌、前端 bundle 無金鑰
  • 使用者輸入有長度限制與基礎過濾（按合規要求）
  • 日誌脫敏；保留期限明確
  • 定期輪換 Key；離職流程含吊销
  • dev / staging / prod Key 分離
  • 瀏覽器與 App 從不直持 Key

存取與入口

網頁入口用於人工試用；API 用於伺服器端整合。兩者模型列表與計費可能不同。

常見問題

通義千問 App 帳號能直接調 API 嗎？

不能預設等同。API 需在百煉控制台單獨建立 Key 並開通計費；聊天產品的額度與 API 帳單分開管理。

API Key 可以放瀏覽器嗎？

不可以。任何下發到瀏覽器的字串都可能被使用者取出。應由後端代為呼叫百煉 API。

OpenAI 相容模式和原生 API 怎麼選？

若已有 OpenAI SDK 封裝，相容模式遷移成本低；新專案可先讀文件對比功能差異（工具呼叫、多模態、結構化輸出）。endpoint 與 model 名以當日文件為準，不要混用過期範例。

模型名報錯怎麼辦？

以控制台與 官方文件 的當前列表為準：可能已更名、未開通或拼寫錯誤。用 MODEL_ID_FROM_DOCS 占位提醒自己每次回查。

如何控制成本？

限制上下文與輸出、快取可複用結果、分檔路由（Turbo/Plus/Max）、設預算告警，並監控異常流量（被刷介面）。

Key 外洩了怎麼辦？

立即在百煉控制台吊销 → 建立新 Key → 排查 Git 歷史、CI 日誌、容器環境變數與前端產物 → 檢查帳單異常呼叫。

官方資源

下一步閱讀

行動路徑

今天：在百煉控制台建立 Key，用環境變數跑通一條占位請求，列印用量與耗時。
明天：加上逾時、429 退避與 schema 校驗，刪除程式裡任何明文 Key。
本週：設預算告警，用 10 條真實輸入做基準，再決定預設模型檔位；提示詞側見 提示詞指南。

相關內容