FabriXAI 用戶指南

# 如何為您的 FabriXAI 代理準備 OpenAPI 規範

OpenAPI 規範（也稱為 Swagger 檔案）是一種廣泛使用的格式，可用於使用 YAML 或 JSON 格式撰寫 API 的文件與進行測試。本指南將協助您為 FabriXAI 代理準備 OpenAPI 規範（Swagger 檔案），以描述該代理的 API 如何運作。您可以選擇使用範本快速開始，或從零開始自訂建構：

# 從範本準備 OpenAPI 規範

FabriXAI 支援兩種類型的代理：網頁應用程式 (Web App) 和 聊天機器人 (Chatbot)。若要了解這兩種類型的差異，請參考：什麼是 AI 代理？

  1. 根據您的代理類型下載對應的 Swagger 範本：

  2. 使用文字編輯器或 Swagger 編輯器 (opens new window) 開啟已下載的 Swagger 範本。

  3. 根據您的代理所設定的輸入欄位更新內容：

    • 對於 網頁應用程式 (Web App) 代理，請找到下列區塊並依據實際需求進行修改：
      path > /completion-messages > post > requestBody > content > application/json > schema > properties > inputs > properties
    • 對於 聊天機器人 (Chatbot) 代理，請找到下列區塊並依據實際需求進行修改：
      path > /chat-messages > post > requestBody > content > application/json > schema > properties > inputs > properties

  4. 範例： 如果您的 Agent 在 使用者輸入 中使用了 key_skills_expertise 和 project_name 這兩個欄位，您可以依照下列方式更新 Swagger 檔案：

        inputs:
        type: object
        description: Contains key/value pairs for text input.
        properties:
            key_skills_expertise:
                type: string
                description: The key skill or expertise that needed for the project to be processed.
            project_name:
                type: string
                description: The name of project to be processed.

# 從零開始建構 OpenAPI 規範

如果您希望有更高的彈性，或需要支援客製化的行為，您也可以選擇從零開始建構 Swagger 檔案，而不是使用範本。這種方式特別適用於進階自訂需求或處理特殊的代理設定情境。

  1. 定義基本結構

    建立一個新的 YAML 檔案（例如 swagger.yaml），並加入以下基本結構：

    openapi: 3.0.0
info:
    title: API Documentation
    version: 1.0.0
servers:
    - url: https://console.fabrixai.com/v1
        description: FabriXAI API Server
components:
    securitySchemes:
        ApiKeyAuth:
        type: apiKey
        in: header
        name: Authorization
        description: "Use the API Key in the 'Authorization' header as 'Bearer {API_KEY}'"

security:
    - ApiKeyAuth: []

  2. 定義 API 端點（Paths）

    現在您可以透過在 paths 區塊下新增 端點，來描述您的 API 可以執行哪些操作。每個端點代表您的代理可以執行的一個動作，例如產生訊息或上傳檔案。

    我們從一個常見的例子開始：產生完成訊息（通常用於 WebApp 代理）。這個端點會告訴系統如何處理請求並產生回應。

    以下是一個您可以直接複製並依需求修改的範例：

    paths:
    /completion-messages:
        post:
        summary: Create Completion Message
        description: Send a request to generate a message.
        security:
            - ApiKeyAuth: []  # This ensures this endpoint requires authentication
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            inputs:
                                type: object
                                description: Contains key/value pairs for text input.
                                properties:
                                    query:
                                    type: string
                                    description: The input text to be processed.
                            response_mode:
                                type: string
                                description: Response mode (streaming or blocking).
                                example: blocking
                            user:
                                type: string
                                description: User identifier for tracking.
                                example: user
        responses:
            '200':
            description: Success
            content:
                application/json:
                schema:
                    type: object
                    properties:
                        message_id:
                            type: string
                            description: Unique message ID
                        conversation_id:
                            type: string
                            description: Conversation ID
                        answer:
                            type: string
                            description: Generated response text
            '400':
                description: 'invalid_param: abnormal parameter input; app_unavailable: App configuration unavailable; provider_not_initialize: no available model credential configuration; provider_quota_exceeded: model invocation quota insufficient; model_currently_not_support: current model unavailable; completion_request_error: text generation failed;'
            '404':
                description: Conversation does not exist
            '500':
                description: Internal server error

    TIP

    WebApp 與 Chatbot 代理的設定差異：

    • WebApp 代理請使用 /completion-messages
    • Chatbot 代理請使用 /chat-messages

    提醒： 您需要將範例中的輸入欄位（如 query 等）替換成您自己的代理實際使用的欄位。詳情請見下一節。

  3. 新增自訂輸入欄位

    和使用範本的方法類似，請依照您代理所設定的輸入欄位來更新 inputs 區塊。

        inputs:
        type: object
        description: Contains key/value pairs for text input.
        properties:
            key_skills_expertise:
                type: string
                description: The key skill or expertise that needed for the project to be processed.
            project_name:
                type: string
                description: The name of project to be processed.

  4. 新增額外的端點（選填）

    如果需要，您可以記錄更多的 API 端點。您可以前往 Agent Builder > Integrations > API 頁面，查看您的 AI 代理所支援的完整端點清單。

    以下是一些常用的端點範例：

    • POST /files/upload - File Upload
    • POST /completion-messages/{task_id}/stop – Stop Completion
    • POST /chat-messages/{task_id}/stop – Stop Chat
    • GET /parameters – Get Agent Parameters
    • POST /messages/{message_id}/feedbacks – Message Feedback
    • GET /messages/{message_id}/suggested – Suggested Questions
    • DELETE /conversations/{conversation_id} – Delete Conversation
    • PUT /conversations/{conversation_id}/name – Rename Conversation
    • GET /meta – Get Conversation Metadata
    • POST /text-to-audio – Text to Audio
    • POST /audio-to-text – Speech to Text

  5. 驗證您的 Swagger 檔案

    1. 開啟 Swagger 編輯器 (opens new window)
    2. 將您的 YAML 檔案貼上到編輯器中
    3. 修正任何語法或結構錯誤，依照提示進行調整

  6. 使用 Swagger UI 測試您的 API

    1. 前往 Swagger 編輯器 (opens new window)
    2. 在任一端點上點選 "Try it out"
    3. 在授權欄位中輸入您的 API 金鑰：
      • 格式為：Bearer {api_key}
      • 將 {api_key} 替換為您實際的 API 金鑰
      • 如果您還沒有金鑰，請參考 整合教學指南
    4. 輸入必要的請求欄位，例如 inputs、response_mode、user
    5. 點選 "Execute" 送出請求並檢視回應

# 相關文章

← 什麼是 AI 代理？ →