---
title: "透過 API 呼叫 ARX 上的地端模型"
description: "取得 model API endpoint、API key 與 model ID，再以 cURL 或 Python SDK，用 OpenAI 或 Claude API 格式呼叫地端模型"
canonical_url: "https://developer.ardge.com/zh-tw/guide/isv/api-model-calls"
---
# 透過 API 呼叫 ARX 上的地端模型

> 取得 model API endpoint、API key 與 model ID，再以 cURL 或 Python SDK，用 OpenAI 或 Claude API 格式呼叫地端模型

## 概觀

ARX 運行於具備 GPU 資源的伺服器上，因此您可以快速部署模型，讓生成式 AI 應用程式在地端進行推論。

ARX model gateway 支援兩種格式：OpenAI API 與 Claude API。您的應用程式可以繼續使用原本熟悉的主流 API 格式，在雲端與地端模型之間切換也因此變得單純。

本文說明呼叫時所需的三個值要去哪裡取得，並提供 cURL 與 Python 範例。

## 您將學到

- 取得 model API endpoint、API key 與 model ID
- 分辨 OpenAI 與 Claude API 兩種格式的差異
- 以 cURL 與 Python SDK 呼叫地端模型

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

## 適用版本

- ARX OS 1.0 以上

## 開始之前

- 您已在 AI Model Center 部署模型，且它在 **Model Instance** 頁面的狀態為 **Running**

若尚未部署，請見 [AI Model Center](https://developer.ardge.com/zh-tw/guide/arx-os/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 model gateway 的網址
    </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>
      請求中 <code>
        model
      </code>
      
       欄位所帶的識別字串
    </td>
    
    <td>
      <strong>
        Home
      </strong>
      
       頁面、<strong>
        API Key › API Endpoint
      </strong>
      
       或 <strong>
        Model Instance
      </strong>
    </td>
  </tr>
</tbody>
</table>

## 步驟 1：取得三個值

### Model API endpoint

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

<note>

`<API_ENDPOINT>`：ARX 介面提供的是含 `/v1` 的 base URL，例如 `http://192.168.1.100/v1`，而以下每個範例都會自行接上各自的路徑。若介面顯示的 endpoint 不需要結尾的 `/v1`，請將它去掉。

</note>

### API key

1. 前往 AI Model Center 的 **API Key** 頁面
2. 點擊 **Add API Key**
3. 依欄位完成設定——您可以為金鑰設定到期日，並選擇它能存取哪些模型
4. 複製產生的金鑰

<tip>

**API key 同時也是存取控制**：

建立時所勾選的模型範圍，就是該金鑰的權限邊界。建議為每個應用程式各建一把金鑰，撤銷其中一把時才不會影響其他應用程式。

</tip>

### Model ID

**Home** 頁面、**API Key › API Endpoint** 頁面與 **Model Instance** 頁面都會顯示模型的 **Instance Name**，該字串即為請求中 `model` 欄位要帶的 model ID。

## 兩種 API 格式的差異

同一組 endpoint 與金鑰在兩種格式下都適用，差異如下：

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

<tbody>
  <tr>
    <td>
      請求路徑
    </td>
    
    <td>
      <code>
        <API_ENDPOINT>/v1/chat/completions
      </code>
    </td>
    
    <td>
      <code>
        <API_ENDPOINT>/v1/messages
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      驗證標頭
    </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 prompt 放在哪
    </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>
        text
      </code>
      
       區塊
    </td>
  </tr>
  
  <tr>
    <td>
      SDK <code>
        base_url
      </code>
    </td>
    
    <td>
      <strong>
        包含
      </strong>
      
       <code>
        /v1
      </code>
    </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>`。

### 列出可用模型

先執行這一則，確認金鑰與 endpoint 都正確：

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

已部署的模型應該會出現在回傳的清單中。

### OpenAI API 格式

```bash
curl <API_ENDPOINT>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [
      {"role": "user", "content": "Explain on-premises model deployment in one sentence."}
    ]
  }'
```

呼叫成功時回傳如下，模型的輸出在 `choices[0].message.content`：

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "<MODEL_ID>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "On-premises model deployment means running an AI model on your own hardware, so your data never leaves for the cloud."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 21, "completion_tokens": 35, "total_tokens": 56 }
}
```

### Claude API 格式

驗證標頭與請求路徑都與 OpenAI 格式不同，且 `max_tokens` 為必填：

```bash
curl <API_ENDPOINT>/v1/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": "Explain on-premises model deployment in one sentence."}
    ]
  }'
```

## 步驟 3：以 Python SDK 呼叫模型

### OpenAI API 格式

安裝套件：

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url=f"{os.environ['ARX_ENDPOINT']}/v1",  # ← 變更 1：指向您的 ARX 裝置
    api_key=os.environ["ARX_API_KEY"],            # ← 變更 2：您的 API key
)

response = client.chat.completions.create(
    model=os.environ["ARX_MODEL_ID"],             # ← 變更 3：model ID
    messages=[
        {"role": "system", "content": "You are a friendly technical assistant. Keep answers short and precise."},
        {"role": "user", "content": "Explain on-premises model deployment in one sentence."},
    ],
)

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

原本就在呼叫 OpenAI 的應用程式不需要改動邏輯，只需要換掉上面標示的三個值。

<warning>

**注意 base_url 的結尾**：

OpenAI SDK 的 `base_url` 必須包含 `/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"],   # ← 變更 1：指向您的 ARX 裝置
    api_key=os.environ["ARX_API_KEY"],     # ← 變更 2：您的 API key
)

message = client.messages.create(
    model=os.environ["ARX_MODEL_ID"],      # ← 變更 3：model ID
    max_tokens=1024,                       # Claude 格式的必填欄位
    system="You are a friendly technical assistant. Keep answers short and precise.",
    messages=[
        {"role": "user", "content": "Explain on-premises model deployment in one sentence."},
    ],
)

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://developer.ardge.com/sitemap.md) for all pages.