API 使用指南
基本介紹
多模型API服務是一個與 OpenAI 相容的 API 服務，允許使用者透過Lightweight Portal訪問 多模型API服務 上的多種模型。
登入服務
- 開啟入口網頁（ https://portal.genai.nchc.org.tw/login ）
- 點選
iService 登入，並登入 iService 帳號。若無 iService 帳號，請先至 iService 網站 申請帳號。
- 自計畫列表選擇欲使用的計畫，點選
前往計畫。若無可用計畫，請參照 iService 申請計畫/專案說明 申請計畫。
請確認計畫已開通使用本服務。 - 成功登入後，即可看到該計畫中的可用額度、API入口 金鑰列表、模型列表等基本資訊。
- 欲登出本服務，請點選右上角之帳號圖像，呼叫下拉式選單後點選
登出。
功能與 Lightweight Portal 使用說明
在 Lightweight Portal 上，使用者可以查看 iService 上已擁有的計畫，包含每個計畫的使用餘額。每個計畫中提供 API入口 金鑰的管理功能，使用者可以在此新增、修改或查看 API入口 金鑰的狀況，以確保訪問權限的安全性和便利性。
- 查看計畫：登入 Lightweight Portal 後，可以清楚查看自己在 iService 上擁有的計畫及各計畫的餘額狀態。
- API入口 金鑰管理：每個計畫中提供 API 入口 金鑰的管理功能，用戶可以生成新的 API入口 金鑰、修改現有的金鑰設定，或查看 API入口 金鑰的狀況，以便於管理和使用。
API入口 金鑰管理
參照登入服務成功登入後，於登入後首頁點選API入口，即可進入 API入口 金鑰的管理頁面。
在這個頁面中，您將會看到計劃中的 API入口 金鑰的詳情，其中包含名稱、使用的頻率限制、當前使用量、可用上限、有效時間及建立時間等資訊，並且可以針對各金鑰進行管理操作。
API入口 金鑰建立
- 使用iService帳號登入後，選擇計畫
- 前往API入口，選擇建立
- 選擇新增
- 填寫金鑰名稱後選擇模型，模型可選擇多個
- 若有預算限制可在下方進階設定中做設定，也可設定金鑰的有效時間
- 設定完成後按下儲存，金鑰請妥善保存
- 建立完成後可在API入口查看金鑰和模型
- 下方卷軸可以拉動查看金鑰資訊
卷軸拉到最後可以對金鑰做查看、修改或刪除
API 使用說明
取得 API入口 金鑰後，使用者便可利用 API入口 存取「多模型API服務」提供的各類模型。詳細的 API 使用方法將會在API功能介紹中介紹，包括使用範例、請求格式、回應結構等，方便使用者快速上手。
其他功能
-
欲切換 UI 介面的「Light」/「Dark」模式，請點選左下角的 ☀️ / 🌙 圖標呼叫選單，並點選欲設置的選項。
-
登入後，可於右上角查看目前登入的使用者之名稱、權限（計畫建立者/計畫管理者/計畫使用者），並且在點選右方帳號圖像時，可確認使用者的名稱及電子信箱。
注意事項
- 帳號安全：請妥善保管 iService 登入資訊及 API入口 金鑰，確保帳號和 API入口 使用的安全性。
- 使用規範：請依照 Lightweight Portal 上的使用規範及說明文件，正確使用 API入口 資源。如有使用限制或流量規範，請參考相關說明。
API功能介紹
本章節介紹四個主要 API 功能，包含Models、 Completions、Chat Completions 和 Embeddings，說明各 API 格式的基本結構和用途。
目錄
Models
概述
Models API 用於查看 API入口 提供的模型列表和其特性。此 API 允許使用者查詢可用模型的相關資訊，適合選擇不同應用需求的模型。
請求格式
Endpoint: /v1/models
HTTP 方法: GET
範例請求:
curl -X 'GET' "https://portal.genai.nchc.org.tw/api/v1/models" \
-H "x-api-key: <您的API KEY>" \
-H 'Content-Type: application/json'
回應格式
- data：包含模型列表，每個模型包含
id、object、created等屬性，提供模型的詳細資訊。
Completions
概述
Completions API 用於根據輸入的提示文本（prompt）生成一段連貫文字，適用於單輪內容生成、摘要、問答、續寫等場景。
請求格式
Endpoint: /v1/completions
HTTP 方法: POST
範例請求:
curl -X POST "https://portal.genai.nchc.org.tw/api/v1/completions" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "Llama3-TAIDE-LX-8B-Instruct-Alpha1",
"prompt": "請寫一篇以未來城市為背景的短篇小說：",
"max_tokens": 200,
"temperature": 0.7
}'
- model：指定使用的模型名稱，例如
Llama3-TAIDE-LX-8B-Instruct-Alpha1。 - prompt：作為輸入的提示文本，模型將根據此文本生成回應。
- temperature (可選)：控制生成內容的隨機性，範圍為 0（穩定）到 1（創意）。
- max_tokens (可選)：生成回應的最大長度（以 token 為單位）。
回應格式
- choices：包含生成的回應列表，每個回應包含
text和finish_reason屬性。 - usage：包含此次請求的 token 使用量統計。
Chat Completions
概述
Chat Completions API 用於生成對話式回應，適合聊天機器人等需要多輪對話的應用。此 API 使用模型來根據給定的對話歷史生成符合上下文的回應。
請求格式
Endpoint: /v1/chat/completions
HTTP 方法: POST
範例請求:
curl -X POST "https://portal.genai.nchc.org.tw/api/v1/chat/completions" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "Llama3-TAIDE-LX-8B-Chat-Alpha1",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant. 你是一個樂於助人的助手。"
},
{
"role": "user",
"content": "請寫一篇小說"
}
],
"max_tokens": 20,
"temperature": 0
}'
- model：指定使用的模型名稱。
- messages：包含對話歷史的列表，每個訊息需包含
role和content屬性。角色 (role) 可為user、assistant或system，分別表示使用者、助理和系統指令的內容。 - temperature (可選)：控制回應的隨機性。範圍通常在 0 到 1 之間，值越高回應越隨機，值越低回應越保守。
- max_tokens (可選)：限制回應中的最大字數，以避免生成過長的回應。
回應格式
- choices：包含生成的回應列表，每個回應包含
message和finish_reason屬性。 - usage：包含此次請求的 token 使用量統計，分別顯示 prompt 和 completion 的 token 數量。
Embeddings
概述
Embeddings API 用於將文本轉換成向量表示，適合語意相似度分析、推薦系統等應用。每段文本會生成一組高維向量來表示其特徵。
請求格式
Endpoint: /v1/embeddings
HTTP 方法: POST
範例請求:
curl -X POST "https://portal.genai.nchc.org.tw/api/v1/embeddings" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "Snowflake/snowflake-arctic-embed-l-v2.0",
"input": "你好"
}'
- model：指定使用的模型名稱。
- input：需要轉換成向量的文本或文本列表。
回應格式
- data：包含生成的向量列表，每個向量包含
index和embedding屬性。 - usage：包含此次請求的 token 使用量統計。
注意事項
- API Key：使用每個 API 需提供有效的 API Key，確保具備適當的訪問權限。
- Rate Limiting：每個 API 使用可能受到頻率限制，請參考 API Portal 的限制說明。
- Error Handling：若請求格式錯誤或資源不足，API 將返回錯誤代碼和訊息，請根據錯誤說明進行修正。