> 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/convai-pixel-streaming-embed/on-premise-deployment.md).

# 配置本地部署

将 Pixel Streaming Embed 包指向你自己的会话服务和流服务器，而不是 Convai 的，用于本地部署和自托管部署。

将嵌入的会话请求及其流路由到你托管的服务，配合 `serviceUrls` 该选项。 当某个体验运行在你自己的 Pixel Streaming 服务器上时，请使用此页。最后，嵌入会向你的服务请求会话，并从你的服务器加载流。

### 前提条件

* 一个已经可与 Convai 配合工作的嵌入。参见 [在 React TypeScript 应用中嵌入体验](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/react-typescript.md) 或 [使用脚本标签嵌入体验](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/cdn-umd-script.md).
* 一个会话服务和一个流服务器，实现本页所述的请求。

### 嵌入如何访问其服务

嵌入会发出两个请求。 `serviceUrls` 会替换每个请求的基础 URL：

| 键                 | 默认值                      | 嵌入发出的请求                                                                |
| ----------------- | ------------------------ | ---------------------------------------------------------------------- |
| `sessionFetch`    | `https://api.convai.com` | `POST <sessionFetch>/xp/streams/viewPublishedExperience` 用于创建会话        |
| `pixelStreamBase` | Convai 的流服务器             | 在 iframe 中加载该会话的流页面，默认来自 `https://x.convai.com/stream-v2/<sessionId>/` |

`sessionFetch` 是一个基础 URL：嵌入会追加 `/xp/streams/viewPublishedExperience` 到其后。

### 设置服务 URL

{% tabs %}
{% tab title="React" %}

```tsx
<PixelStreamComponent
  expId="YOUR_EXPERIENCE_ID"
  serviceUrls={{
    sessionFetch: 'https://sessions.example.com',
    pixelStreamBase: 'https://stream.example.com',
  }}
/>
```

{% endtab %}

{% tab title="JavaScript" %}

```js
const experience = new PixelStreamCore.PixelStreamClient({
  container: document.getElementById('experience'),
  expId: 'YOUR_EXPERIENCE_ID',
  serviceUrls: {
    sessionFetch: 'https://sessions.example.com',
    pixelStreamBase: 'https://stream.example.com/stream-v2/',
  },
});
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
React 组件和无框架客户端构建流 URL 的方式不同。 `PixelStreamComponent` 加载 `<pixelStreamBase>/stream-v2/<sessionId>/`. `PixelStreamClient` 加载 `<pixelStreamBase><sessionId>/`，中间没有分隔符，所以请将其结尾设为 `pixelStreamBase` 会话路径，包括末尾的 `/`.
{% endhint %}

### 实现会话服务

嵌入向会话服务发送一个 JSON 正文：

```json
{
  "experience_id": "YOUR_EXPERIENCE_ID",
  "allocate_server": false,
  "end_user_id": "user-123"
}
```

`end_user_id` 仅在嵌入具有 `endUserId`时才会出现。当嵌入具有 `authToken`时，请求会在其中携带它， `API-AUTH-TOKEN` 标头。

嵌入按如下方式读取响应：

| 响应                                                        | 结果           |
| --------------------------------------------------------- | ------------ |
| 状态 `200` ，带有 `{ "session": { "session_id": "<id>" } }`    | 嵌入会为 `<id>`. |
| 状态 `200` ，带有 `{ "status": "retry", "message": "<text>" }` | 嵌入会显示其错误屏幕。  |
| 任何其他状态，且带有 `{ "ERROR": "<text>" }`                        | 嵌入会显示其错误屏幕。  |

流页面加载后，嵌入会向其发送一个 JSON 字符串， `{"type":"SESSION_ID","sessionId":"<id>"}`，并且在 `endUserId` 已设置时，一个 `END_USER_ID` 携带 `end_user_id` 和 `end_user_metadata`.

### 验证部署

加载页面并打开浏览器的网络面板。

{% hint style="success" %}
会话请求发送到你的 `sessionFetch` URL，且 iframe 从你的 `pixelStreamBase` URL。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/87b57936662c69d8802f20f500191b181163cf02" %}
[Pixel Streaming Embed API 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-pixel-streaming-embed/api-reference.md)
{% endcontent-ref %}


---

# 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/convai-pixel-streaming-embed/on-premise-deployment.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.