> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/self-hosted-deployments.md).

# 连接到自托管部署

将 Web SDK 指向你自己的 Convai 部署，而不是 Convai 的托管服务，设置它调用的每个主机，并将请求和 API 密钥保留在你的网络内。

将 Web SDK 指向你自行运行的 Convai 部署，例如本地部署或私有云安装，而不是 Convai 的托管服务。当你的角色运行在以下位置之外时，请使用此页： `api.convai.com`，或者当浏览器不得访问 Convai 的公共主机时。

SDK 不使用单一基础 URL。它会与多个服务通信，而在 Convai 的托管服务中，每个服务都有自己的主机。请将你使用的每个服务都设置为你部署中对应的主机。

### 先决条件

* Convai Web SDK 2.0 或更高版本。如果你使用预构建的聊天小组件， `@convai/web-widget` 安装在其旁边。
* 你部署中每个服务的公共 URL。你的部署管理员可以提供这些地址。

### 设置主机

| 选项                  | 服务         | 托管默认值                             | 调用它的组件                                                                                                    |
| ------------------- | ---------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `url`               | 核心服务（实时）   | `https://realtime-api.convai.com` | `connect()`，会将内容发布到 `{url}/connect`                                                                       |
| `characterInfoUrl`  | 角色信息       | `https://api.convai.com`          | 来自 `@convai/web-widget`，它使用以下接口查找角色的名称和头像： `POST /character/get`                                          |
| `characterApiUrl`   | 角色 REST 平台 | `https://api2.convai.com`         | `client.characterVersions`                                                                                |
| `interactionApiUrl` | 交互 API     | 无                                 | SSE 传输。参见 [通过 SSE 传输进行聊天](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/sse-transport.md). |

将它们与凭据放在同一个配置对象中传入。它在以下两种情况下的工作方式相同： `new ConvaiClient(...)` 来自 `@convai/web-sdk/core` 以及 `useConvaiClient(...)` 在 React 中。

```ts
import { ConvaiClient } from '@convai/web-sdk/core';

const client = new ConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  url: 'https://realtime-api.example.com',
  characterInfoUrl: 'https://api.example.com',
  characterApiUrl: 'https://api2.example.com',
});

await client.connect();
```

将 `example.com` 主机替换为你部署中的主机。仅使用 origin，不要带路径，也不要带类似以下内容的尾随路由： `/connect`.

你无需配置 LiveKit。核心服务会在其 `/connect` 响应中返回 LiveKit 房间 URL，因此设置 `url` 对于 WebRTC 传输来说就足够了。在 WebSocket 传输中，客户端会使用 `wss://` 每当你的页面或 `url` 通过 HTTPS 提供时。

### 即使聊天看起来正常，也要设置 characterInfoUrl

SDK 本身不会向此主机发出请求；它将该值作为 `client.characterInfoUrl`，并且来自 `@convai/web-widget` 的聊天小组件会从那里读取它。如果你不设置 `characterInfoUrl` ，小组件会将其角色查找请求发送到 `https://api.convai.com`，你的 API 密钥也会随该请求一起发送。在受限网络中，这既是一次失败的请求，也是在向网络外的主机发送凭据。

这种失败很难察觉。没有查找时，小组件仍然可以工作。它会显示备用名称 `Convi` 以及没有头像，因此缺少设置看起来更像是一个视觉问题，而不是错误。如果你的小组件标题显示 `Convi` 而不是你角色的名称，请先检查此设置。

该查找会使用 `CONVAI-API-KEY` 标头进行身份验证，当你传入 `apiKey`，或 `API-AUTH-TOKEN` 当你传入 `authToken`。配置你的部署的 `POST /character/get` 以接受相同的标头。直到 1.9.2 的 SDK 版本会将 API 密钥作为 `X-API-Key`，而自托管部署会拒绝 `401`.

`characterInfoUrl` 并且 `characterApiUrl` 是独立的选项，因为它们是不同的服务。角色 REST 平台不提供 `/character/get`，因此一个值不能同时用于两者。

### 为其他 API 设置主机

SDK 的某些部分是在客户端之外创建的，并且会带上各自的主机：

* **长期记忆。** 将你部署的 API origin 作为第四个参数传入： `new MemoryManager(apiKey, characterId, endUserId, 'https://api.example.com')`。它默认为 `https://api.convai.com`时发送。参见 [使用长期记忆](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/long-term-memory.md).
* **已发布的文本聊天。** 同时传入发布 API origin 和核心 origin，例如 `loadPublishedChatSession(publicationId, 'https://api.example.com')` 并且 `connectWithPublicationGrant(launchToken, { url: 'https://realtime-api.example.com' })`时发送。参见 [连接到已发布的文本聊天](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/published-text-chat.md).

### 在没有 TURN 的情况下连接到 LiveKit 服务器

客户端默认使用 `iceTransportPolicy: 'relay'`，这会仅通过 TURN 服务器发送媒体。Convai 的托管 LiveKit 提供了一个。如果你的 LiveKit 部署没有 TURN 服务器，请设置 `iceTransportPolicy: 'all'` ，这样浏览器也可以使用直连：

```ts
const client = new ConvaiClient({
  apiKey: 'YOUR_API_KEY',
  characterId: 'YOUR_CHARACTER_ID',
  url: 'https://realtime-api.example.com',
  iceTransportPolicy: 'all',
});
```

SSE 和 WebSocket 传输不使用 WebRTC，因此会忽略此选项。

### 故障排查

| 症状                                                                   | 原因                                                       | 修复                                                                                                                             |
| -------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 小组件标题显示 `Convi` 且没有头像。                                               | `characterInfoUrl` 未设置或设置错误，因此角色查找失败。                    | 设置 `characterInfoUrl` 到你部署的 API origin。                                                                                        |
| `POST {characterInfoUrl}/character/get` 返回 `401`，在 SDK 1.9.2 或更早版本中。 | 这些版本将 API 密钥作为 `X-API-Key`发送，而你的部署期望的是 `CONVAI-API-KEY`. | 升级 SDK。                                                                                                                        |
| 一个到 `api.convai.com` 的请求出现在浏览器的网络日志中。                                | 此页上的某个选项未设置。                                             | 将请求路径与上表对照，并设置匹配的选项。                                                                                                           |
| 首次连接失败，错误为 `未找到 v1 RTC 路径。请考虑升级你的 LiveKit 服务器版本`.                    | 你的 LiveKit 服务器版本早于 `livekit-client` 2.x，而 SDK 使用的是该版本。   | 升级 LiveKit 服务器。没有哪个 SDK 版本能改变这一点。                                                                                              |
| 使用 `characterVersion` 会失败，并出现 `503 无法解析角色版本`.                        | 你的部署不解析角色版本。                                             | 省略 `characterVersion`时发送。参见 [连接到某个角色版本](/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/character-versioning.md). |
| 在没有 TURN 的 LiveKit 服务器上，WebRTC 已连接但没有音频流动。                           | 默认的 `中继` 策略仅允许 TURN 连接。                                  | 设置 `iceTransportPolicy: 'all'`.                                                                                                |

### API 参考

| 选项                   | 类型                 | 默认值                               | 描述                                                                                                           |
| -------------------- | ------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `url`                | `string`           | `https://realtime-api.convai.com` | 核心服务的 origin。客户端会向 `{url}/connect`.                                                                          |
| `characterInfoUrl`   | `string`           | `https://api.convai.com`          | 提供以下内容的源： `POST /character/get`发送请求，由 `@convai/web-widget` 聊天小组件用于显示角色名称和头像。将其读取为 `client.characterInfoUrl`. |
| `characterApiUrl`    | `string`           | `https://api2.convai.com`         | 角色 REST 平台的 origin，用于 `client.characterVersions`.                                                            |
| `interactionApiUrl`  | `string`           | 无                                 | SSE 端点。设置它会在 `transport` 已省略。                                                                                |
| `iceTransportPolicy` | `"relay" \| "all"` | `"relay"`                         | WebRTC ICE 策略。用于 `"all"` 没有 TURN 的 LiveKit 服务器。                                                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/self-hosted-deployments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.