特殊模型說明

特殊模型介紹

本章節節錄特殊模型API的重點說明供使用上作為參考。目前依RAP平台包含的模型類別先介紹 gpt-oss-safeguard、Automatic Speech Recognition (ASR)、Text-to-Speech (TTS)、Rerank，並說明此模型的概述、特別用法去指出它和一般模型的主要差異。

gpt-oss-safeguard

概述

gpt-oss-safeguard 是第一個專為安全分類任務訓練的開放權重推理模型，旨在根據可自訂的策略對文字內容進行分類。專為信任與安全工作流程而設計。它是一個遵循策略的模型，能夠可靠地解釋和執行編寫的標準，並說明其決策原因。該模型的邏輯使其非常適合與以可審計性和可自訂性為基礎的大型安全系統整合。

特別用法

由於其特性，如果要使用gpt-oss-safeguard 此類模型做判斷的話需要使用者在 system prompt 裡面定義好 Policy Prompts。

Policy Prompts 定義了模型行為的操作邊界。與人工審核員編寫的內容或平台策略類似 oss-safeguard 的策略應明確規定哪些行為構成違規、哪些行為是允許的，以及如何將這些區別傳達給信任與安全系統的其他決策環節。

有效的 Policy Prompts 經過精心設計，能夠區分相似的內容類型，識別隱晦的、編碼的或間接的違規行為，並防止在極端情況下出現誤報。

Policy Prompts 的結構

Instruction: 模型必須做什麼以及模型應該如何回答
Definitions: 關鍵字的簡明解釋
Criteria: 區分違規內容和非違規內容
Examples: 決策邊界附近的簡短、具體的實例。重要的是，既要有你想分類的例子，也要有你想排除的例子

由於 oss-safeguard 專為結構化審核而設計，因此它需要明確的回應指令。如果 Policy Prompts 遵循一致的模式，包括預期的回應和輸出格式，則其效能可能會更好。建議使用Harmony 格式的結構:
```
# Policy Name

## INSTRUCTIONS

Describe what oss-safeguard should do and how to respond.

## DEFINITIONS

Clarify key terms and context.

## VIOLATES (1)

Describe behaviors or content that should be flagged.

## SAFE (0)

Describe content that should not be flagged.

## EXAMPLES

Provide 4–6 short examples labeled 0 or 1.

Content: [INPUT]
Answer (0 or 1):
```

Policy Prompts 的範例

## Policy Definitions

### Key Terms

**[Term 1]**: [Definition]

**[Term 2]**: [Definition]

**[Term 3]**: [Definition]

## Content Classification Rules

### VIOLATES Policy (Label: 1)

Content that:

- [Violation 1]
- [Violation 2]
- [Violation 3]
- [Violation 4]
- [Violation 5]

### DOES NOT Violate Policy (Label: 0)

Content that is:

- [Acceptable 1]
- [Acceptable 2]
- [Acceptable 3]
- [Acceptable 4]
- [Acceptable 5]

## Examples

### Example 1 (Label: 1)

**Content**: "[Example]"

**Expected Response**:

### Example 2 (Label: 1)

**Content**: "[Example]"

**Expected Response**:

### Example 3 (Label: 0)

**Content**: "[Example]"

**Expected Response**:

### Example 4 (Label: 0)

**Content**: "[Example]"

**Expected Response**:

官方資料來源

以上僅節錄 gpt-oss-safeguard 的重要差異，若想要更深入了解介紹、適用族群以及完整使用指南請到官方網頁查看:

https://cookbook.openai.com/articles/gpt-oss-safeguard-guide

Automatic Speech Recognition (ASR)

概述

Audio Transcriptions API 用於將使用者上傳的音訊檔案轉換為文字 - Automatic Speech Recognition, ASR，適用於語音轉文字、逐字稿產生、字幕製作、多語言語音辨識等場景。

特別用法

請求格式

Endpoint: /v1/audio/transcriptions

HTTP 方法: POST

範例請求 for Linux:

curl https://portal.genai.nchc.org.tw/api/v1/audio/transcriptions \
-H "Authorization: Bearer <您的_API_KEY>" \
--fail \
-F "file=@<音檔路徑>" \
-F "model=Whisper-Large-V3"

範例請求 for windows PowerShell:

curl.exe https://portal.genai.nchc.org.tw/api/v1/audio/transcriptions `
-H "Authorization: Bearer <您的_API_KEY>" `
-F "file=@C:\path\to\audio.wav" `   # 音檔放置的本機路徑
-F "model=Whisper-Large-V3"

回應格式

task：固定為 "transcribe"，表示此次請求執行的是語音轉文字（轉錄）任務
language：模型自動判斷的語言代碼（例如 en、zh）。
duration：音檔長度（單位：秒）。
text：完整的語音辨識結果，為模型轉錄後的文字內容。
segments：語音分段資訊陣列，每一筆分段包含對應的時間區間與文字內容，可用於字幕、時間軸標註或進階分析。
usage：本次請求的使用量資訊（部分平台可能為 null）。

補充說明

為確保 Whisper-Large-V3（同步 ASR API）的穩定性與效能，建議如下：檔案大小：單次處理建議 ≤ 200MB，超過可能影響穩定性。WAV（無損）：建議 ≤ 20 分鐘（約 200MB），檔案隨時長線性成長。MP3（壓縮）：建議 ≤ 150 分鐘，適合長音檔；大小會隨位元速率而異。建議規格總結：WAV ≤ 20 分鐘（~200MB），MP3 ≤ 150 分鐘；超出請分段或轉檔
支援轉錄的音訊檔案物件（非檔案名稱），格式需為以下其中一種: flac、mp3、mpga、ogg、wav

Text-to-Speech (TTS)

概述

Audio Speech API 用於將輸入的文字內容轉換為語音 - Text-to-Speech, TTS，適用於語音播報、語音助理、客服系統、多媒體內容產生等場景。

特別用法

請求格式

Endpoint: /v1/audio/speech

HTTP 方法: POST

範例請求 for Linux:

curl https://portal.genai.nchc.org.tw/api/v1/audio/speech \
-H "Authorization: Bearer <您的_API_KEY>" \
-H "Content-Type: application/json" \
--fail \
-d '{
    "model": "truku-male-tts",
    "input": "The quick brown fox jumped over the lazy dog.",
    "voice": "alloy"
}' \
--output speech.wav

範例請求 for windows PowerShell:

@'
{
  "model": "truku-male-tts",
  "input": "The quick brown fox jumped over the lazy dog.",
  "voice": "alloy"
}
'@ | Set-Content -Encoding utf8 -NoNewline .\tts.json

curl.exe https://portal.genai.nchc.org.tw/api/v1/audio/speech `
-H "Authorization: Bearer <您的_API_KEY>" `
-H "Content-Type: application/json" `
--fail `
--data-binary "@tts.json" `
--output speech.wav

建議使用 curl.exe，以避免 PowerShell 版本差異造成 binary 音訊處理問題。

參數說明（Request Body）

model：指定使用的文字轉語音模型，例如 truku-male-tts。
input：要轉換為語音的文字內容。
voice：語音聲線設定（必填），用於指定輸出的語音類型

回應格式

audio：回傳結果為二進位音訊資料（binary audio），需搭配 --output 參數儲存為音訊檔案。
response_format：音訊輸出格式，建議使用 wav 以利驗證與播放。
錯誤處理（建議）：搭配 --fail 參數，避免錯誤回應被寫入音訊檔案，造成副檔名與實際內容不一致。

補充說明

TTS API 不建議使用 SSE（Server-Sent Events），請使用一次性 audio 回傳方式。
成功請求時，終端機不會輸出文字內容，語音資料會直接寫入指定的音訊檔案。

Rerank

概述

Rerank API 用於對一組文件進行語義相關性排序。給定一個查詢（Query）和一組文件（Documents），API 會計算每個文件與查詢之間的相關性分數，並按分數從高到低回傳排序後的結果。這適用於提升搜尋精準度、RAG（檢索增強生成）架構中的第二階段精煉等場景。

特別用法

請求格式

Endpoint: /v1/rerank

HTTP 方法: POST

範例請求 for Linux:

curl https://portal.genai.nchc.org.tw/api/v1/rerank \
-H "Authorization: Bearer <您的_API_KEY>" \
-H "Content-Type: application/json" \
--fail \
-d '{
    "model": "BGE-Reranker-V2-M3",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
      "Carson City is the capital city of the American state of Nevada.",
      "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
      "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
      "Capitalization or capitalisation in English grammar is the use of a capital letter at the start of a word.",
      "Capital punishment has existed in the United States since before the United States was a country."
    ]
  }'

--output
'{
  "id": "rerank-da81182be45e40ad99b7a380aa5b8b8d",
  "results": [
    {
      "index": 2,
      "relevance_score": 0.9969866871833801,
      "document": {
        "text": "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district."
      }
    },
    {
      "index": 0,
      "relevance_score": 0.011851305142045021,
      "document": {
        "text": "Carson City is the capital city of the American state of Nevada."
      }
    },
    {
      "index": 1,
      "relevance_score": 0.0012187735410407186,
      "document": {
        "text": "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan."
      }
    }
  ],
  "meta": {
    "billed_units": {
      "total_tokens": 195
    },
    "tokens": {
      "input_tokens": 195
    }
  }
}'

範例請求 for windows PowerShell:

@'
{
  "model": "BGE-Reranker-V2-M3",
  "query": "What is the capital of the United States?",
  "top_n": 3,
  "documents": [
    "Carson City is the capital city of the American state of Nevada.",
    "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan.",
    "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district.",
    "Capitalization or capitalisation in English grammar is the use of a capital letter at the start of a word.",
    "Capital punishment has existed in the United States since before the United States was a country."
  ]
}
'@ | Set-Content -Encoding utf8 -NoNewline .\rerank.json

curl.exe https://portal.genai.nchc.org.tw/api/v1/rerank `
-H "Authorization: Bearer <您的_API_KEY>" `
-H "Content-Type: application/json" `
--fail `
--data-binary "@rerank.json"

--output
'{
  "id": "rerank-29b81980a2594afda2007f45f7b67c1f",
  "results": [
    {
      "index": 2,
      "relevance_score": 0.9969866871833801,
      "document": {
        "text": "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district."
      }
    },
    {
      "index": 0,
      "relevance_score": 0.011851305142045021,
      "document": {
        "text": "Carson City is the capital city of the American state of Nevada."
      }
    },
    {
      "index": 1,
      "relevance_score": 0.0012187735410407186,
      "document": {
        "text": "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean. Its capital is Saipan."
      }
    }
  ],
  "meta": {
    "billed_units": {
      "total_tokens": 195
    },
    "tokens": {
      "input_tokens": 195
    }
  }
}'

參數說明（Request Body）

model：指定使用的 Rerank 模型，例如 BGE-Reranker-V2-M3。
query：搜尋查詢字串，即您想要問的問題或搜尋的關鍵字。
documents：字串陣列，包含所有待排序的文件內容。
top_n（選填）：指定回傳相關性最高的前 N 筆結果。若未指定，則回傳所有文件的排序結果。

回應格式

API 回傳 JSON 格式資料，包含以下欄位：

id：本次請求的唯一識別碼。
results：排序後的結果陣列，每一項包含：
index：該文件在原始 documents 陣列中的索引位置（從 0 開始）。
relevance_score：相關性分數（0 到 1 之間），分數越高代表越相關。
document：包含該文件的內容（部分實作可能包含此欄位）。
meta：包含使用量資訊，如 total_tokens（總消耗 Token 數）。

補充說明

效能建議：對於長文件，模型會自動進行截斷（通常為 512 或 1024 tokens，視模型設定而定）。建議傳入的文件長度適中，以獲得最佳排序效果。

特殊模型介紹​

gpt-oss-safeguard​

概述​

特別用法​

官方資料來源​

Automatic Speech Recognition (ASR)​

概述​

特別用法​

請求格式​

回應格式​

補充說明​

Text-to-Speech (TTS)​

概述​

特別用法​

請求格式​

參數說明（Request Body）​

回應格式​

補充說明​

Rerank​

概述​

特別用法​

請求格式​

參數說明（Request Body）​

回應格式​

補充說明​

特殊模型介紹

gpt-oss-safeguard

概述

特別用法

官方資料來源

Automatic Speech Recognition (ASR)

概述

特別用法

請求格式

回應格式

補充說明

Text-to-Speech (TTS)

概述

特別用法

請求格式

參數說明（Request Body）

回應格式

補充說明

Rerank

概述

特別用法

請求格式

參數說明（Request Body）

回應格式

補充說明