> ## 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.

# Giới thiệu

> Khám phá các quy trình API được thiết kế để tải tài liệu lên liền mạch, tìm kiếm ngữ nghĩa mạnh mẽ và quản lý hội thoại hiệu quả

## Chào mừng

Chào mừng bạn đến với trang tài liệu API của Shieldbase AI! API của chúng tôi cung cấp các endpoint trực quan để tải tài liệu lên một cách liền mạch, thực hiện tìm kiếm ngữ nghĩa nâng cao và quản lý các cuộc hội thoại linh hoạt. Hãy khám phá hai quy trình chính dưới đây để khai thác hiệu quả các tính năng mạnh mẽ này.

### Xác thực

Trước khi bắt đầu, hãy đảm bảo tất cả các yêu cầu API của bạn đều bao gồm ba header sau. Các header này là bắt buộc đối với mọi yêu cầu nhằm xác thực và cấp quyền truy cập của bạn vào hệ thống:

* **client-id**: Mã định danh khách hàng duy nhất của bạn.
* **private-key**: Khóa riêng tư dùng để xác thực các lệnh gọi API của bạn.
* **secret**: Khóa bí mật cung cấp thêm một lớp bảo mật.

<Note>
  Để lấy `client-id`, `private-key` và `secret`, vui lòng truy cập
  [https://app.sbai.cloud/](https://app.sbai.cloud/) và đăng nhập vào
  tài khoản của bạn hoặc gửi email cho chúng tôi tại [support@shieldbase.ai](mailto:support@shieldbase.ai). Sau khi có các thông tin xác thực này, bạn có thể bắt đầu gửi
  các yêu cầu đã được xác thực.
</Note>

Các header này cần được đưa vào mọi yêu cầu bạn gửi đến API.

***

## Models API

Truy xuất các mô hình khả dụng cho các tác vụ như tìm kiếm ngữ nghĩa và quản lý hội thoại thông qua endpoint `GET /external/models`. Phản hồi trả về một mảng các mô hình, mỗi mô hình có `label` và `value` để dễ dàng tham chiếu.

### Endpoint

**GET** `/external/models`

### Header

Hãy đảm bảo đưa các header sau vào yêu cầu của bạn để xác thực:

* **client-id**: Mã định danh khách hàng duy nhất của bạn.
* **private-key**: Khóa riêng tư dùng để xác thực các lệnh gọi API của bạn.
* **secret**: Khóa bí mật cung cấp thêm bảo mật cho các yêu cầu của bạn.

### Phản hồi

Khi yêu cầu thành công, phản hồi sẽ bao gồm một mảng các mô hình khả dụng, mỗi mô hình được biểu diễn dưới dạng một đối tượng với các thuộc tính sau:

* **label**: Tên dễ đọc của mô hình.
* **value**: Mã định danh của mô hình, được dùng khi chỉ định mô hình cần sử dụng.

### Ví dụ phản hồi

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

***

### Quy trình 1: Tải lên và tìm kiếm ngữ nghĩa

Quy trình này cho phép bạn tải tài liệu lên và thực hiện tìm kiếm ngữ nghĩa trên các tệp đã tải lên. Đây là quy trình gồm hai bước: Trước tiên, bạn tải tài liệu lên, sau đó sử dụng endpoint tìm kiếm ngữ nghĩa để truy xuất tất cả nội dung liên quan.

#### Bước 1: Tải tài liệu lên

<Card title="Tải tài liệu lên" icon="file" href="/vi/api-reference/endpoint/public/upload-document">
  Bắt đầu bằng cách tải lên một hoặc nhiều tài liệu bằng endpoint API tải tài liệu
  của chúng tôi. Đây là bước đầu tiên trong quy trình và yêu cầu bạn gửi các
  tệp như một phần của yêu cầu `multipart/form-data`. Hãy đảm bảo bạn đưa vào
  tất cả các header bắt buộc như `client-id`, `private-key` và `secret`.
</Card>

Để tải lên một tài liệu hoặc một nhóm tài liệu, hãy sử dụng endpoint `PUT /external/upload`. Endpoint này cho phép bạn tải lên các tệp ở nhiều định dạng khác nhau. Bạn cần đưa các tệp vào dưới dạng dữ liệu nhị phân trong form data, và máy chủ sẽ xử lý chúng để hỗ trợ tìm kiếm ngữ nghĩa và các tính năng khác sau đó. Khi tải lên thành công, máy chủ sẽ trả về một thông báo xác nhận.

#### Bước 2: Thực hiện tìm kiếm ngữ nghĩa

<Card title="Tìm kiếm ngữ nghĩa" icon="magnifying-glass" href="/vi/api-reference/endpoint/public/search-index">
  Sau khi tải tài liệu lên, bạn có thể truy xuất tài liệu và nội dung của chúng theo ngữ nghĩa bằng từ khóa
  hoặc ngữ cảnh thông qua endpoint tìm kiếm ngữ nghĩa của chúng tôi. Điều này giúp bạn tìm tài liệu
  dựa trên nội dung và mức độ tương đồng, giúp việc truy xuất dễ dàng và hiệu quả hơn.
</Card>

Sau khi tài liệu đã được tải lên, bạn có thể sử dụng endpoint `POST /external/semantic-search` để truy xuất nội dung dựa trên từ khóa hoặc truy vấn được chỉ định. Bạn cũng có thể thu hẹp phạm vi tìm kiếm bằng cách cung cấp ID ngữ cảnh nếu cần. Endpoint này sẽ trả về các tài liệu liên quan nhất, giúp bạn dễ dàng truy cập thông tin mình cần.

***

### Quy trình 2: Quản lý hội thoại

API quản lý hội thoại của chúng tôi cho phép bạn bắt đầu, tiếp tục và quản lý các cuộc hội thoại theo cách lập trình. Luồng hội thoại bắt đầu bằng việc khởi tạo một cuộc hội thoại mới, gửi tin nhắn vào đó và tiếp tục cuộc hội thoại khi cần.

#### Bước 1: Bắt đầu cuộc hội thoại mới

<Card title="Bắt đầu cuộc hội thoại" icon="comments" href="/vi/api-reference/endpoint/public/start-conversation-public">
  Bắt đầu một cuộc hội thoại mới bằng cách gửi tin nhắn đầu tiên đến API
  hội thoại. Endpoint này sẽ tạo một ID hội thoại mới được dùng để
  theo dõi cuộc hội thoại.
</Card>

Để khởi tạo một cuộc hội thoại mới, hãy sử dụng endpoint `POST /external/start-conversation`. Bạn cần cung cấp tin nhắn mà bạn muốn dùng để bắt đầu cuộc hội thoại. Máy chủ sẽ phản hồi với `conversation_id` và `model` cùng với các thông tin chi tiết ban đầu của cuộc hội thoại, chẳng hạn như tin nhắn, số lượng ner và dấu thời gian.

### Ví dụ phản hồi cho 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"
  }
}
```

#### Bước 2: Gửi tin nhắn trong cuộc hội thoại

<Card title="Gửi tin nhắn" icon="paper-plane" href="/vi/api-reference/endpoint/public/send-conversation-public">
  Sau khi cuộc hội thoại đã bắt đầu, bạn có thể gửi thêm tin nhắn để
  tiếp tục trao đổi. Điều này giúp mở rộng cuộc hội thoại với thông tin
  mới.
</Card>

Để tiếp tục trao đổi, hãy sử dụng endpoint `POST /external/send`. Đưa `conversation_id` nhận được từ endpoint `start-conversation` và tin nhắn mới của bạn vào phần thân của yêu cầu. Điều này giúp giữ nguyên luồng hội thoại, đảm bảo mỗi tin nhắn được liên kết đúng với cuộc hội thoại của nó.

### Ví dụ phản hồi cho 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"
}
```

#### Bước 3: Tiếp tục cuộc hội thoại

<Card title="Tiếp tục cuộc hội thoại" icon="arrow-right" href="/vi/api-reference/endpoint/public/continue-conversation-public">
  Sử dụng endpoint này để tiếp tục cuộc hội thoại đang diễn ra bằng cách thêm các phản hồi mới
  vào đó. Điều này đảm bảo cuộc hội thoại có thể phát triển theo thời gian.
</Card>

Nếu muốn mở rộng thêm cuộc hội thoại, bạn cần sử dụng endpoint `POST /external/continue`, cung cấp `conversation_id`, `model` và mọi thông tin bổ sung cần thiết để duy trì cuộc hội thoại. Sau khi gọi `continue-conversation`, bạn có thể quay lại endpoint `send-conversation` để gửi tin nhắn mới trong cùng ngữ cảnh hội thoại.

### Ví dụ phản hồi cho 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"
}
```