> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldbase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 簡介

> 探索專為順暢的文件上傳、強大的語意搜尋與高效對話管理所設計的 API 工作流程

## 歡迎

歡迎來到 Shieldbase AI API 文件網站!我們的 API 提供直覺的端點,讓您能順暢地上傳文件、執行進階語意搜尋,並管理動態對話。請參考以下兩個主要工作流程,有效運用這些強大功能。

### 驗證

開始之前,請確保所有 API 請求皆包含下列三個標頭。這些標頭為所有請求的必要欄位,用於驗證並授權您對系統的存取:

* **client-id**: 您的專屬用戶端識別碼。
* **private-key**: 用於驗證您 API 呼叫的私鑰。
* **secret**: 提供額外安全層的密鑰。

<Note>
  若要取得 `client-id`、`private-key` 與 `secret`,請前往
  [https://app.sbai.cloud/](https://app.sbai.cloud/) 並登入您的帳號,
  或來信至 [support@shieldbase.ai](mailto:support@shieldbase.ai)。取得這些憑證後,
  您即可開始發送經驗證的請求。
</Note>

請在您發送至 API 的每個請求中皆包含這些標頭。

***

## Models API

透過 `GET /external/models` 端點取得可用於語意搜尋與對話管理等任務的模型清單。回應會回傳模型的陣列,每個模型都包含便於參照的 `label` 與 `value`。

### 端點

**GET** `/external/models`

### 標頭

請務必在請求中包含下列標頭以進行驗證:

* **client-id**: 您的專屬用戶端識別碼。
* **private-key**: 用於驗證 API 呼叫的私鑰。
* **secret**: 為您的請求提供額外安全層的密鑰。

### 回應

當請求成功時,回應會包含可用模型的陣列,每個模型以物件表示,具備下列屬性:

* **label**: 模型的人類可讀名稱。
* **value**: 模型的識別碼,於指定要使用的模型時使用。

### 回應範例

```json theme={null}
[
  {
    "label": "GPT-3.5",
    "value": "gpt-3.5"
  },
  {
    "label": "GPT4o",
    "value": "gpt4o"
  }
]
```

***

### 工作流程 1: 上傳與語意搜尋

此工作流程可讓您上傳文件,並對已上傳的檔案進行語意搜尋。這是兩階段的流程:先上傳您的文件,接著使用語意搜尋端點來取得所有相關內容。

#### 步驟 1: 上傳文件

<Card title="上傳文件" icon="file" href="/zh-tw/api-reference/endpoint/public/upload-document">
  首先,使用我們的文件上傳 API 端點上傳一份或多份文件。這是流程的第一步,需以 `multipart/form-data` 請求的形式傳送檔案。請務必包含所有必要標頭,例如 `client-id`、`private-key` 與 `secret`。
</Card>

要上傳一份或多份文件,請使用 `PUT /external/upload` 端點。這讓您可以上傳各種格式的檔案。您需要在表單資料中將檔案以二進位資料的方式包含進來,伺服器會處理這些檔案,以便後續啟用語意搜尋等功能。上傳成功後,伺服器會回傳確認訊息。

#### 步驟 2: 執行語意搜尋

<Card title="語意搜尋" icon="magnifying-glass" href="/zh-tw/api-reference/endpoint/public/search-index">
  上傳文件後,可以使用關鍵字或情境,透過我們的語意搜尋端點以語意方式取得文件及其內容。這幫助您根據內容與相似度尋找文件,讓檢索更輕鬆且更有效率。
</Card>

文件上傳完成後,您可以使用 `POST /external/semantic-search` 端點,依指定的關鍵字或查詢取得內容。若有需要,還可以透過提供 context ID 進一步縮小搜尋範圍。此端點會回傳最相關的文件,讓您能輕鬆存取所需資訊。

***

### 工作流程 2: 對話管理

我們的對話管理 API 讓您能以程式方式開始、繼續並管理對話。對話流程從建立新對話開始,接著傳送訊息給該對話,並在需要時繼續對話。

#### 步驟 1: 開始新對話

<Card title="開始對話" icon="comments" href="/zh-tw/api-reference/endpoint/public/start-conversation-public">
  透過傳送初始訊息給對話 API 來開始新的對話。此端點會建立新的對話 ID,用於追蹤該對話。
</Card>

若要開始新的對話,請使用 `POST /external/start-conversation` 端點。您需要提供想用來開始對話的訊息。伺服器會回傳 `conversation_id` 與 `model`,以及訊息、ner 數量、時間戳記等初始對話資訊。

### Start Conversation 的回應範例

```json theme={null}
{
  "conversation_id": "<string>",
  "title": "<string>",
  "messages": {
    "id": "<string>",
    "text": "<string>",
    "redacted": "<string>",
    "synthetic": "<string>",
    "ner_count": 123,
    "response": "<string>",
    "ner_items": [],
    "timestamp": "2023-11-07T05:31:56Z"
  }
}
```

#### 步驟 2: 在對話中傳送訊息

<Card title="傳送訊息" icon="paper-plane" href="/zh-tw/api-reference/endpoint/public/send-conversation-public">
  對話開始後,您可以傳送額外的訊息以延續對話。這有助於用新的資訊擴充對話。
</Card>

若要繼續對話,請使用 `POST /external/send` 端點。在請求內容中包含從 `start-conversation` 端點取得的 `conversation_id`,以及您的新訊息。這能維持對話流程的完整性,確保每則訊息正確地連結到對應的對話。

### Send Conversation 的回應範例

```json theme={null}
{
  "conversation_id": "<string>",
  "sender": "ai | sender",
  "message_text": "<string>",
  "redacted_text": "<string>",
  "syntactic_text": "<string>",
  "model": "gpt-4o",
  "related_questions": ["<string>"],
  "id": "<string>",
  "typing_completed": true,
  "created_at": "2023-11-07T05:31:56Z"
}
```

#### 步驟 3: 繼續對話

<Card title="繼續對話" icon="arrow-right" href="/zh-tw/api-reference/endpoint/public/continue-conversation-public">
  使用此端點以新回應的方式延續正在進行的對話。這能讓對話隨著時間發展。
</Card>

若您想進一步擴充對話,需使用 `POST /external/continue` 端點,提供 `conversation_id`、`model` 與其他必要資訊,以維持對話的進行。在呼叫 `continue-conversation` 後,您可以回到 `send-conversation` 端點,在同一個對話情境中送出新訊息。

### Continue Conversation 的回應範例

```json theme={null}
{
  "conversation_id": "d0c73687-cc8d-4628-be2d-01050d32dfb6",
  "sender": "user",
  "message_text": "<string>",
  "redacted_text": "<string>",
  "syntactic_text": "<string>",
  "typing_completed": true,
  "created_at": "2024-08-16T09:24:07.865867",
  "ner_items": [],
  "ner_count": 123,
  "title": "Dropbox: A Popular File Sharing Service",
  "id": "ac3ca0a0-69ee-49c3-a6a5-86ee9b9f4c0e"
}
```