---
title: "透過 API 呼叫 ARX 平台上的地端模型"
description: "取得 Model API Endpoint、API Key 與 Model ID，並以 cURL 與 Python SDK 用 OpenAI 或 Claude API 格式呼叫地端模型"
canonical_url: "https://docs.ardge.com/zh-tw/knowledge/arx-os/api-model-calls"
---
# 透過 API 呼叫 ARX 平台上的地端模型

> 取得 Model API Endpoint、API Key 與 Model ID，並以 cURL 與 Python SDK 用 OpenAI 或 Claude API 格式呼叫地端模型

## 概觀

ARX 系統運行於具備 GPU 資源的伺服器，可在其上快速部署模型，為生成式 AI 應用程式提供 AI 能力。

ARX 的模型閘道支援 OpenAI API 與 Claude API 兩種格式。應用程式沿用主流模型 API 格式即可取用地端模型，也便於在雲端模型與地端模型之間切換。

本文說明呼叫模型所需的三項資訊如何取得，並提供 cURL 與 Python 的呼叫範例。

## 你將學會什麼

- 取得 Model API Endpoint、API Key 與 Model ID
- 辨別 OpenAI API 與 Claude API 兩種格式的差異
- 以 cURL 與 Python SDK 呼叫地端模型

**預計時間：約 10 分鐘**

## 適用版本

- ARX OS 1.0 及以上版本

## 開始之前

- 已於 AI Model Center 完成模型部署，且該模型於 **Model Instances** 頁面的狀態為 **Running**

若尚未部署模型，下載與部署的完整流程請參考 [AI Model Center](https://docs.ardge.com/zh-tw/guide/use-ai/ai-model-center)。

## 你需要準備的資訊

呼叫模型須具備下列三項資訊：

<table>
<thead>
  <tr>
    <th>
      資訊
    </th>
    
    <th>
      說明
    </th>
    
    <th>
      取得位置
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Model API Endpoint
      </strong>
    </td>
    
    <td>
      ARX 平台模型閘道的網址
    </td>
    
    <td>
      AI Model Center 的 <strong>
        Home
      </strong>
      
       頁面，或 <strong>
        API Key › API Endpoint
      </strong>
      
       頁面
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        API Key
      </strong>
    </td>
    
    <td>
      通過呼叫驗證所需的憑證
    </td>
    
    <td>
      AI Model Center 的 <strong>
        API Key
      </strong>
      
       頁面（須自行建立）
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Model ID
      </strong>
    </td>
    
    <td>
      API 請求中 <code>
        model
      </code>
      
       欄位所填的識別字串
    </td>
    
    <td>
      AI Model Center 的 <strong>
        Home
      </strong>
      
       頁面、<strong>
        API Key › API Endpoint
      </strong>
      
       頁面，或 <strong>
        Model Instances
      </strong>
      
       頁面
    </td>
  </tr>
</tbody>
</table>

## 步驟 1：取得三項必要資訊

### Model API Endpoint

前往 AI Model Center 的 **Home** 頁面，或 **API Key › API Endpoint** 頁面查看。

<note>

**<API_ENDPOINT> 已含 /ai/v1：**

ARX 介面顯示的端點結尾為 `/ai/v1`，例如 `http://192.168.1.100/ai/v1`，路徑由各範例自行接上。

</note>

### API Key

1. 前往 AI Model Center 的 **API Key** 頁面
2. 點擊 **Add API Key** 按鈕
3. 依欄位引導完成設定，其中可指定 API Key 的到期時間，以及此 API Key 可取用的模型
4. 複製產生的金鑰

<tip>

**可透過 API Key 進行權限控管：**

建立時所指定的可取用模型範圍，即為該金鑰的權限邊界。建議依應用程式分別建立金鑰，日後撤銷時不影響其他應用程式。

</tip>

### Model ID

於 **Home** 頁面、**API Key › API Endpoint** 頁面或 **Model Instances** 頁面，皆會顯示模型的 **Instance Name**。此字串即為 API 請求中 `model` 欄位所填的 Model ID。

## 兩種 API 格式的差異

同一組端點與金鑰可同時以兩種格式呼叫，差異如下：

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      OpenAI API 格式
    </th>
    
    <th>
      Claude API 格式
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      請求路徑
    </td>
    
    <td>
      <code>
        <API_ENDPOINT>/chat/completions
      </code>
    </td>
    
    <td>
      <code>
        <API_ENDPOINT>/messages
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      認證 Header
    </td>
    
    <td>
      <code>
        Authorization: Bearer <YOUR_API_KEY>
      </code>
    </td>
    
    <td>
      <code>
        x-api-key: <YOUR_API_KEY>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        max_tokens
      </code>
    </td>
    
    <td>
      選填
    </td>
    
    <td>
      必填
    </td>
  </tr>
  
  <tr>
    <td>
      System 提示的位置
    </td>
    
    <td>
      <code>
        messages
      </code>
      
       陣列中 <code>
        role
      </code>
      
       為 <code>
        system
      </code>
      
       的項目
    </td>
    
    <td>
      獨立的 <code>
        system
      </code>
      
       欄位
    </td>
  </tr>
  
  <tr>
    <td>
      回覆內容的位置
    </td>
    
    <td>
      <code>
        choices[0].message.content
      </code>
    </td>
    
    <td>
      <code>
        content
      </code>
      
       陣列中 <code>
        type
      </code>
      
       為 <code>
        text
      </code>
      
       的區塊
    </td>
  </tr>
  
  <tr>
    <td>
      SDK 的 <code>
        base_url
      </code>
    </td>
    
    <td>
      <strong>
        直接使用
      </strong>
      
      介面顯示的端點
    </td>
    
    <td>
      端點<strong>
        去除
      </strong>
      
      結尾的 <code>
        /v1
      </code>
    </td>
  </tr>
</tbody>
</table>

選擇依據為既有應用程式所使用的 SDK：原本呼叫 OpenAI 者沿用 OpenAI 格式，原本呼叫 Claude 者沿用 Claude 格式，皆無須改寫程式邏輯。

## 步驟 2：以 cURL 發出第一個請求

開始之前，請將三個佔位符替換為步驟 1 取得的資訊：`<API_ENDPOINT>`、`<YOUR_API_KEY>`、`<MODEL_ID>`。

### 列出可用模型

此請求可先行確認金鑰與端點皆正確：

```bash
curl <API_ENDPOINT>/models \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

回應的清單中應出現已部署的模型。

### OpenAI API 格式

```bash
curl <API_ENDPOINT>/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [
      {"role": "user", "content": "請用一句話說明什麼是地端模型部署。"}
    ]
  }'
```

回應成功時將收到類似下列內容，模型輸出的文字位於 `choices[0].message.content`：

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "<MODEL_ID>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "地端模型部署是指將 AI 模型安裝在自己的裝置上執行，資料不需傳送到雲端。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 21, "completion_tokens": 35, "total_tokens": 56 }
}
```

### Claude API 格式

認證 Header 與請求路徑皆與 OpenAI 格式不同，且 `max_tokens` 為必填：

```bash
curl <API_ENDPOINT>/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "<MODEL_ID>",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "請用一句話說明什麼是地端模型部署。"}
    ]
  }'
```

## 步驟 3：以 Python SDK 呼叫

### OpenAI API 格式

安裝套件：

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["ARX_ENDPOINT"],  # ← 須修改處 1：指向你的 ARX 裝置
    api_key=os.environ["ARX_API_KEY"],    # ← 須修改處 2：你的 API 金鑰
)

response = client.chat.completions.create(
    model=os.environ["ARX_MODEL_ID"],     # ← 須修改處 3：模型 ID
    messages=[
        {"role": "system", "content": "你是一位親切的技術助理，回答請簡潔明確。"},
        {"role": "user", "content": "請用一句話說明什麼是地端模型部署。"},
    ],
)

print(response.choices[0].message.content)
```

原本即呼叫 OpenAI 的應用程式，程式邏輯無須變更，僅需替換上述標註的三處。

<warning>

**注意 base_url 的結尾：**

OpenAI SDK 的 `base_url` 直接使用介面顯示的端點（結尾為 `/ai/v1`），後續的 `/chat/completions` 由 SDK 自動接上。

</warning>

### Claude API 格式

安裝套件：

```bash
pip install anthropic
```

```python
import os
import anthropic

client = anthropic.Anthropic(
    base_url=os.environ["ARX_ENDPOINT"].removesuffix("/v1"),  # ← 須修改處 1：指向你的 ARX 裝置
    api_key=os.environ["ARX_API_KEY"],                        # ← 須修改處 2：你的 API 金鑰
)

message = client.messages.create(
    model=os.environ["ARX_MODEL_ID"],                         # ← 須修改處 3：模型 ID
    max_tokens=1024,                                          # Claude 格式必填
    system="你是一位親切的技術助理，回答請簡潔明確。",
    messages=[
        {"role": "user", "content": "請用一句話說明什麼是地端模型部署。"},
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)
```

<warning>

**Claude SDK 的 base_url 須去除結尾的 /v1：**

Anthropic SDK 會自動接上 `/v1/messages`，此點與 OpenAI SDK 相反。

</warning>

## 官方 API 文件

各欄位的完整說明請參考原廠文件：

- OpenAI API：[https://developers.openai.com/api/docs](https://developers.openai.com/api/docs)
- Claude API：[https://platform.claude.com/docs/en/api/overview](https://platform.claude.com/docs/en/api/overview)


## Sitemap

See the full [sitemap](https://docs.ardge.com/sitemap.md) for all pages.