<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="zh">
    <title>𝐗𝐒𝐈 𝐂𝐨𝐧𝐭𝐫𝐨𝐥</title>
    <subtitle>XSI 多租户云服务：自带上游 Key 的 AI API Router</subtitle>
    <link rel="self" type="application/atom+xml" href="https://xsicontrol.com/atom.xml"/>
    <link rel="alternate" type="text/html" href="https://xsicontrol.com"/>
    <generator uri="https://www.getzola.org/">Zola</generator>
    <updated>2026-11-19T00:00:00+08:00</updated>
    <id>https://xsicontrol.com/atom.xml</id>
    <entry xml:lang="zh">
        <title>WebSocket 与实时接口</title>
        <published>2026-11-19T00:00:00+08:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/api-reference/realtime/"/>
        <id>https://xsicontrol.com/docs/api-reference/realtime/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/api-reference/realtime/">&lt;h1 id=&quot;websocket-yu-shi-shi-jie-kou&quot;&gt;WebSocket 与实时接口&lt;&#x2F;h1&gt;
&lt;p&gt;XSI 为长连接与实时语音场景提供专门的适配器。它们与 HTTP 接口共用同一个入口和同一套认证、权限、计费体系。&lt;&#x2F;p&gt;
&lt;p&gt;一个请求同时满足以下条件时按 WebSocket 处理：&lt;code&gt;Connection&lt;&#x2F;code&gt; 含 &lt;code&gt;upgrade&lt;&#x2F;code&gt;、&lt;code&gt;Upgrade: websocket&lt;&#x2F;code&gt;、&lt;code&gt;Sec-WebSocket-Key&lt;&#x2F;code&gt; 非空。&lt;&#x2F;p&gt;
&lt;div class=&quot;infobox&quot;&gt;
通过反向代理部署时，API 域名必须允许 WebSocket 升级，见《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;》。
&lt;&#x2F;div&gt;
&lt;h2 id=&quot;gong-gong-gui-ze&quot;&gt;公共规则&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;项目&lt;&#x2F;th&gt;&lt;th&gt;规则&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;认证&lt;&#x2F;td&gt;&lt;td&gt;与 HTTP 相同，使用 &lt;code&gt;Authorization&lt;&#x2F;code&gt;、&lt;code&gt;x-api-key&lt;&#x2F;code&gt; 或 &lt;code&gt;x-goog-api-key&lt;&#x2F;code&gt; 请求头&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;单帧上限&lt;&#x2F;td&gt;&lt;td&gt;16 MiB&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;单连接时长&lt;&#x2F;td&gt;&lt;td&gt;默认 60 分钟（&lt;code&gt;WS_MAX_CONN_DURATION&lt;&#x2F;code&gt;）；DashScope Realtime 默认 120 分钟&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;握手前失败&lt;&#x2F;td&gt;&lt;td&gt;以 HTTP 状态码加纯文本返回，上游不可用时为 &lt;code&gt;502 WebSocket upstream failure&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;服务关闭中&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;503 Server is shutting down&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;转发前处理&lt;&#x2F;td&gt;&lt;td&gt;剥离调用方凭证、&lt;code&gt;Sec-WebSocket-*&lt;&#x2F;code&gt; 等逐跳头；子协议 &lt;code&gt;openai-insecure-api-key.*&lt;&#x2F;code&gt; 与 &lt;code&gt;bearer.*&lt;&#x2F;code&gt; 不会发给上游&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;浏览器无法为 WebSocket 设置自定义请求头，而 XSI 不把 &lt;code&gt;openai-insecure-api-key.*&lt;&#x2F;code&gt; 子协议当作 XSI 凭证。浏览器端实时语音请使用 &lt;a href=&quot;https:&#x2F;&#x2F;xsicontrol.com&#x2F;docs&#x2F;api-reference&#x2F;realtime&#x2F;#realtime-webrtc&quot;&gt;Realtime WebRTC&lt;&#x2F;a&gt; 或由服务端代理连接。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;responses-websocket-mo-shi&quot;&gt;Responses WebSocket 模式&lt;&#x2F;h2&gt;
&lt;p&gt;与 OpenAI Responses WebSocket 模式语义一致：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;wss:&#x2F;&#x2F;&amp;lt;API 域名&amp;gt;&#x2F;v1&#x2F;responses&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ul&gt;
&lt;li&gt;每个 &lt;code&gt;response.create&lt;&#x2F;code&gt;（以及 &lt;code&gt;response.steer&lt;&#x2F;code&gt;）都会独立做准入：资源白名单、账号状态与额度、账号级限速、模型白名单与模型限额。&lt;&#x2F;li&gt;
&lt;li&gt;准入失败时，XSI 发送一个错误事件后关闭连接：&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;json&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;type&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;error&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;status&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 403&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;error&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;message&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;...&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;type&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;...&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;code&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;...&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;status&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 403&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;retryable&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; false&lt;&#x2F;span&gt;&lt;span&gt;}}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;模型白名单或模型限额不通过时，此处一律为 &lt;code&gt;403&lt;&#x2F;code&gt;（HTTP 接口中模型限额返回 &lt;code&gt;429&lt;&#x2F;code&gt;）。&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;粘性会话只依据握手请求头 &lt;code&gt;session_id&lt;&#x2F;code&gt;、&lt;code&gt;conversation_id&lt;&#x2F;code&gt;、&lt;code&gt;session-id&lt;&#x2F;code&gt;、&lt;code&gt;thread-id&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;首次连接上游时最多尝试 3 个 Key（&lt;code&gt;WS_RESPONSES_INITIAL_CONNECT_ATTEMPTS&lt;&#x2F;code&gt;）。&lt;&#x2F;li&gt;
&lt;li&gt;每个 response 按上游返回的用量单独计费。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;Codex 的 WebSocket 配置示例见《&lt;a href=&quot;&#x2F;docs&#x2F;tools&#x2F;codex&#x2F;&quot;&gt;Codex CLI &#x2F; App&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;realtime&quot;&gt;Realtime&lt;&#x2F;h2&gt;
&lt;h3 id=&quot;websocket&quot;&gt;WebSocket&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;wss:&#x2F;&#x2F;&amp;lt;API 域名&amp;gt;&#x2F;v1&#x2F;realtime?model=&amp;lt;model&amp;gt;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;&#x2F;realtime&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;realtime&lt;&#x2F;code&gt; 均可。模型来自查询参数 &lt;code&gt;model&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;每条连接在建立时做一次账号级限速检查。&lt;&#x2F;li&gt;
&lt;li&gt;支持 &lt;code&gt;api.openai.com&lt;&#x2F;code&gt; 与阿里云 DashScope（&lt;code&gt;dashscope.aliyuncs.com&lt;&#x2F;code&gt;、&lt;code&gt;dashscope-intl.aliyuncs.com&lt;&#x2F;code&gt;，XSI 自动映射到 &lt;code&gt;&#x2F;api-ws&#x2F;v1&#x2F;realtime&lt;&#x2F;code&gt;）上游。&lt;&#x2F;li&gt;
&lt;li&gt;附着到已存在的 WebRTC 通话：&lt;code&gt;?call_id=&amp;lt;XSI 返回的通话 ID&amp;gt;&lt;&#x2F;code&gt;。XSI 会校验通话属于当前账号且模型一致，找不到时返回 &lt;code&gt;404&lt;&#x2F;code&gt;，模型不一致时返回 &lt;code&gt;409&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;&lt;a id=&quot;realtime-webrtc&quot;&gt;&lt;&#x2F;a&gt;&lt;&#x2F;p&gt;
&lt;h3 id=&quot;webrtc-tong-hua&quot;&gt;WebRTC 通话&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;POST &#x2F;v1&#x2F;realtime&#x2F;calls&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ul&gt;
&lt;li&gt;请求体为 JSON 或 multipart，必须包含 &lt;code&gt;sdp&lt;&#x2F;code&gt; 与 &lt;code&gt;session.model&lt;&#x2F;code&gt;，大小不超过 4 MiB；只接受 POST，否则返回 &lt;code&gt;405&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;仅使用 &lt;code&gt;api.openai.com&lt;&#x2F;code&gt; 上游 Key：Key 池为空时返回 &lt;code&gt;503 No available key&lt;&#x2F;code&gt;，选中的 Key 不是 OpenAI 时返回 &lt;code&gt;503 No available Realtime provider key&lt;&#x2F;code&gt;。请求体超过 4 MiB 返回 &lt;code&gt;400 Invalid realtime call body&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;响应中的 &lt;code&gt;Location&lt;&#x2F;code&gt; 被改写为 &lt;code&gt;&#x2F;v1&#x2F;realtime&#x2F;calls&#x2F;&amp;lt;XSI 通话 ID&amp;gt;&lt;&#x2F;code&gt;，绑定有效期 65 分钟。服务端可用这个 ID 通过 WebSocket &lt;code&gt;?call_id=&lt;&#x2F;code&gt; 附着到通话。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h3 id=&quot;lin-shi-ke-hu-duan-mi-yao&quot;&gt;临时客户端密钥&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;POST &#x2F;v1&#x2F;realtime&#x2F;client_secrets&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;透传给上游。用于路由、权限与计费的模型名依次取请求体顶层 &lt;code&gt;model&lt;&#x2F;code&gt;、查询参数 &lt;code&gt;model&lt;&#x2F;code&gt;，都没有时为 &lt;code&gt;gpt-realtime&lt;&#x2F;code&gt;；&lt;code&gt;session.model&lt;&#x2F;code&gt; 不参与判断。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;live-hui-hua&quot;&gt;Live 会话&lt;&#x2F;h2&gt;
&lt;p&gt;Live 是面向 &lt;code&gt;gpt-live-1&lt;&#x2F;code&gt; 的实时会话接口，按时长计费。WebRTC 会话在上游建会成功后起计 15 秒，之后按累计时长抵扣；主 WebSocket 按上游上报的秒数计费；委托给其他模型的 Token 与工具费用另计。&lt;&#x2F;p&gt;
&lt;p&gt;&lt;strong&gt;WebRTC（HTTP）&lt;&#x2F;strong&gt;&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;POST &#x2F;v1&#x2F;live&#x2F;sessions&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;请求体为 JSON，必须包含 &lt;code&gt;session.model&lt;&#x2F;code&gt;（非空，≤ 256 字节）、&lt;code&gt;transport.type = &quot;webrtc&quot;&lt;&#x2F;code&gt; 与 &lt;code&gt;transport.sdp&lt;&#x2F;code&gt;，大小不超过 4 MiB。&lt;&#x2F;p&gt;
&lt;p&gt;&lt;strong&gt;WebSocket&lt;&#x2F;strong&gt;&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;wss:&#x2F;&#x2F;&amp;lt;API 域名&amp;gt;&#x2F;v1&#x2F;live&#x2F;sessions&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;wss:&#x2F;&#x2F;&amp;lt;API 域名&amp;gt;&#x2F;v1&#x2F;live&#x2F;sessions&#x2F;{id}&#x2F;attach&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ul&gt;
&lt;li&gt;主连接（&lt;code&gt;&#x2F;v1&#x2F;live&#x2F;sessions&lt;&#x2F;code&gt;）升级后，须在 30 秒内发送首帧 &lt;code&gt;{&quot;type&quot;: &quot;session.start&quot;, &quot;session&quot;: {&quot;model&quot;: &quot;gpt-live-1&quot;}}&lt;&#x2F;code&gt;（≤ 4 MiB）；附着连接（&lt;code&gt;&#x2F;attach&lt;&#x2F;code&gt;）直接使用已有会话，不能再发送 &lt;code&gt;session.start&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;不接受查询参数，否则返回 &lt;code&gt;400 Live sessions do not accept query parameters; put the model in session.start&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;映射后的模型必须是 &lt;code&gt;gpt-live-1&lt;&#x2F;code&gt;。WebRTC 建会以 HTTP &lt;code&gt;400 Public Live sessions require gpt-live-1&lt;&#x2F;code&gt; 返回；WebSocket 升级后发生的错误以错误事件与关闭帧报告。&lt;&#x2F;li&gt;
&lt;li&gt;仅使用 OpenAI 上游 Key，或 &lt;code&gt;config.provider_type&lt;&#x2F;code&gt; 为 &lt;code&gt;openai-live&lt;&#x2F;code&gt; 的兼容上游。&lt;&#x2F;li&gt;
&lt;li&gt;账号级限速在 &lt;code&gt;session.start&lt;&#x2F;code&gt; 时检查。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;deepseek-yu-yin-he-cheng-websocket&quot;&gt;DeepSeek 语音合成 WebSocket&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;wss:&#x2F;&#x2F;&amp;lt;API 域名&amp;gt;&#x2F;v1&#x2F;tools&#x2F;tts&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ul&gt;
&lt;li&gt;仅适用于 DeepSeek 上游，消息格式与 DeepSeek 官方一致。&lt;&#x2F;li&gt;
&lt;li&gt;认证可以使用请求头，也可以在浏览器中使用子协议：&lt;code&gt;Sec-WebSocket-Protocol: tts, bearer.&amp;lt;XSI API Key&amp;gt;&lt;&#x2F;code&gt;。该子协议凭证只对这一路由有效。&lt;&#x2F;li&gt;
&lt;li&gt;按客户端提交的累计字符数计费（汉字计 2 个字符）：会话结束时只要已提交字符且未收到失败的 &lt;code&gt;finish&lt;&#x2F;code&gt; 事件即计费，提前断开也可能计费。&lt;&#x2F;li&gt;
&lt;li&gt;请使用带 &lt;code&gt;&#x2F;v1&lt;&#x2F;code&gt; 的路径。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;proxy&#x2F;&quot;&gt;Router API&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;guides&#x2F;deepseek&#x2F;&quot;&gt;DeepSeek 全家桶接入&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>架构</title>
        <published>2026-11-19T00:00:00+08:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/concepts/architecture/"/>
        <id>https://xsicontrol.com/docs/concepts/architecture/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/concepts/architecture/">&lt;p&gt;XSI 是一个用 Go 编写的单进程 HTTP 服务：同一个端口既承载模型调用（数据面），也承载账号、Key 与配置管理（控制面）。状态保存在 PostgreSQL 与 Redis 中，两个静态控制台通过 HTTP API 与之交互。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;zu-jian&quot;&gt;组件&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;                 ┌──────────────────────────────┐&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;   应用 &#x2F; SDK ──▶│                              │──▶ OpenAI &#x2F; Azure&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;   Codex      ──▶│   XSI API（Go，:3443）        │──▶ Anthropic&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;   Claude Code ─▶│   ├─ 数据面：&#x2F;v1&#x2F;... 等       │──▶ Gemini &#x2F; Vertex&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;   控制台     ──▶│   └─ 控制面：&#x2F;x-*、&#x2F;dashboard │──▶ DeepSeek &#x2F; xAI &#x2F; ...&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;                 └───────┬───────────────┬──────┘&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;                         │               │&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;                  PostgreSQL           Redis ──▶ 邮件服务（SMTP）&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;              账号、Key、账本      配置、缓存、用量、&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;                                   计数、消息、邮件队列&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;组件&lt;&#x2F;th&gt;&lt;th&gt;镜像&lt;&#x2F;th&gt;&lt;th&gt;职责&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;API&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;proxyxai&#x2F;xsi&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;认证、准入、路由、转发、计量、计费与全部管理接口&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;控制台&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;proxyxai&#x2F;xsi-pages&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;配置管理（Admin）与账户管理（Manage）两个静态站点，中英文各一份&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;邮件服务&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;proxyxai&#x2F;mail&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;消费 Redis 邮件队列并通过 SMTP 投递；API 本身不直连 SMTP&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;PostgreSQL&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;postgres:18&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;账号、上游 Key、充值账本、通知发件箱&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Redis&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;redis:alpine&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;租户配置、账号缓存、用量统计、限速计数、粘性绑定、跨实例消息；DB 1 为邮件队列&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;qing-qiu-sheng-ming-zhou-qi&quot;&gt;请求生命周期&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;请求 ─▶ 体积预检 ─▶ 认证 ─▶ 账号准入 ─▶ 模型解析 ─▶ 模型准入 ─▶ Level ─▶ 选 Key ─▶ 转发&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;                                                                                 │&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;        结算 ◀─ 用量提取（旁路解析响应 &#x2F; SSE） ◀─ 重试（同组换 Key，可跨组） ◀──────┘&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;体积预检&lt;&#x2F;strong&gt;：声明的 &lt;code&gt;Content-Length&lt;&#x2F;code&gt; 超过上限时，在认证前直接返回 &lt;code&gt;413&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;认证&lt;&#x2F;strong&gt;：从 &lt;code&gt;Authorization&lt;&#x2F;code&gt;、&lt;code&gt;x-api-key&lt;&#x2F;code&gt; 或 &lt;code&gt;x-goog-api-key&lt;&#x2F;code&gt; 读取 Key；内存命中直接放行，否则依次查 Redis 与 PostgreSQL。认证失败按 IP 计数并临时封禁。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;账号准入&lt;&#x2F;strong&gt;：IP 白名单、账号状态与冻结、日&#x2F;月额度、余额、账号级限速、资源白名单。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;模型解析&lt;&#x2F;strong&gt;：一次扫描 JSON 顶层字段（&lt;code&gt;model&lt;&#x2F;code&gt;、&lt;code&gt;stream&lt;&#x2F;code&gt;、&lt;code&gt;prompt_cache_key&lt;&#x2F;code&gt;、&lt;code&gt;speed&lt;&#x2F;code&gt;、&lt;code&gt;service_tier&lt;&#x2F;code&gt;），按映射规则得到上游模型名，并原地改写请求体或 URL。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;模型准入&lt;&#x2F;strong&gt;：模型白名单与模型级限额。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;Level 与 Key 选择&lt;&#x2F;strong&gt;：按 &lt;code&gt;LEVEL_MAPPER&lt;&#x2F;code&gt; 确定分组，在该组的 Key 池中按粘性会话或轮询选择 Key。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;转发&lt;&#x2F;strong&gt;：剥离调用方凭证与转发头，按上游主机改写路径与鉴权头。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;重试&lt;&#x2F;strong&gt;：上游返回可重试错误时，在向客户端写出任何字节之前换 Key 重试。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;计量与结算&lt;&#x2F;strong&gt;：非流式响应在完整读取后解析用量；SSE 流在转发的同时逐块解析，不缓存整个流。结算在请求结束时执行一次，客户端中途断开也会按实际用量结算。&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;h2 id=&quot;zhuang-tai-yu-huan-cun&quot;&gt;状态与缓存&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;层级&lt;&#x2F;th&gt;&lt;th&gt;位置&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;账号热状态&lt;&#x2F;td&gt;&lt;td&gt;进程内存 → Redis → PostgreSQL&lt;&#x2F;td&gt;&lt;td&gt;读按此顺序回源；余额与用量先在内存累计，按批次落 Redis 与数据库&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;租户配置&lt;&#x2F;td&gt;&lt;td&gt;进程内快照&lt;&#x2F;td&gt;&lt;td&gt;来自 Redis，写时复制；通过发布订阅与每 3 分钟的版本巡检在实例间同步&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Key 池&lt;&#x2F;td&gt;&lt;td&gt;进程内，每租户每 Level 一个轮询环&lt;&#x2F;td&gt;&lt;td&gt;懒加载，Key 变更时重建&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;运行时映射&lt;&#x2F;td&gt;&lt;td&gt;账号与租户的精确匹配缓存&lt;&#x2F;td&gt;&lt;td&gt;通配解析结果沉淀为精确项，避免重复匹配&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;价格&lt;&#x2F;td&gt;&lt;td&gt;进程内，每租户一份有效价格与模型匹配索引&lt;&#x2F;td&gt;&lt;td&gt;启动时加载 &lt;code&gt;pricing.json&lt;&#x2F;code&gt;，租户覆盖按需合并&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;用量统计&lt;&#x2F;td&gt;&lt;td&gt;进程内 + Redis&lt;&#x2F;td&gt;&lt;td&gt;每账号每日、每月一份，按模型细分&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;粘性绑定&lt;&#x2F;td&gt;&lt;td&gt;单实例在内存，多实例在 Redis&lt;&#x2F;td&gt;&lt;td&gt;默认保留 24 小时&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;PostgreSQL 只保存账号、Key 与账本等权威数据；高频变化的用量统计保存在 Redis。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;jia-mi-mo-xing&quot;&gt;加密模型&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;每个租户拥有一把随机生成的&lt;strong&gt;租户密钥&lt;&#x2F;strong&gt;。上游 Provider Key 与 Vertex 私钥使用租户密钥加密后入库，算法为 XChaCha20-Poly1305。&lt;&#x2F;li&gt;
&lt;li&gt;租户密钥本身用&lt;strong&gt;账号自己的 API Key&lt;&#x2F;strong&gt; 加密，保存在账号记录中。服务端不保存可直接解开租户密钥的明文材料。&lt;&#x2F;li&gt;
&lt;li&gt;因此，某个租户的 Key 池在该租户有账号发起请求时才能被解密加载；数据库被单独拿走时，上游 Key 无法直接解密。&lt;&#x2F;li&gt;
&lt;li&gt;账号 Key 轮换时，租户密钥会用新 Key 重新加密，旧 Key 立即失效。&lt;&#x2F;li&gt;
&lt;li&gt;进程启动时禁用内存转储。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;dan-shi-li-yu-duo-shi-li&quot;&gt;单实例与多实例&lt;&#x2F;h2&gt;
&lt;p&gt;&lt;code&gt;SINGLE_MODE&lt;&#x2F;code&gt; 默认 &lt;code&gt;true&lt;&#x2F;code&gt;。单实例模式下，限速计数、粘性绑定与变更通知都在进程内完成，延迟最低。需要横向扩展时设为 &lt;code&gt;false&lt;&#x2F;code&gt;：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;方面&lt;&#x2F;th&gt;&lt;th&gt;单实例（默认）&lt;&#x2F;th&gt;&lt;th&gt;多实例（&lt;code&gt;SINGLE_MODE=false&lt;&#x2F;code&gt;）&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;限速计数&lt;&#x2F;td&gt;&lt;td&gt;进程内&lt;&#x2F;td&gt;&lt;td&gt;Redis&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Key 与账号变更通知&lt;&#x2F;td&gt;&lt;td&gt;进程内通道&lt;&#x2F;td&gt;&lt;td&gt;Redis 发布订阅&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;粘性绑定&lt;&#x2F;td&gt;&lt;td&gt;内存&lt;&#x2F;td&gt;&lt;td&gt;Redis&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;用量写入 Redis&lt;&#x2F;td&gt;&lt;td&gt;维护与落盘时&lt;&#x2F;td&gt;&lt;td&gt;每次更新&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Key 自动禁用&#x2F;删除广播&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;Redis 频道&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;多实例部署时，分组切换（&lt;code&gt;SWITCH_OVER&lt;&#x2F;code&gt;）、模型故障替换与失败计数仍按实例独立判断；自动休眠也只作用于触发它的实例。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;gao-xing-neng-she-ji&quot;&gt;高性能设计&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;连接复用&lt;&#x2F;strong&gt;：所有 HTTP 上游请求共享一个 &lt;code&gt;http.Transport&lt;&#x2F;code&gt;（WebSocket 使用独立的拨号器）（每主机最多 256 个空闲连接、2048 个并发连接，启用 HTTP&#x2F;2 与 TLS 会话缓存），读写缓冲各 64 KiB，并通过 &lt;code&gt;sync.Pool&lt;&#x2F;code&gt; 复用缓冲区。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;零拷贝流式&lt;&#x2F;strong&gt;：SSE 响应直接从上游复制到客户端，用量跟踪器在旁路逐块解析，不缓冲整个响应（XSI 请求上游不压缩；个别上游仍返回压缩流时，计量会缓存该响应）。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;最小化解析&lt;&#x2F;strong&gt;：请求体只扫描一次顶层字段，模型改写用原地 JSON 修改，不做完整反序列化。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;异步结算&lt;&#x2F;strong&gt;：用量计算、扣费与状态落盘由按账号分片的后台 worker 完成，不阻塞请求路径。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;热路径缓存&lt;&#x2F;strong&gt;：认证、配置、映射、Key 池与价格均在进程内命中；配置与 Key 池加载使用 singleflight 合并并发回源。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;无超时截断&lt;&#x2F;strong&gt;：HTTP 服务器只设置读头超时（15 秒）与空闲超时（2 分钟），长时间流式响应不会被服务器截断；上游响应头等待上限默认 1800 秒。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;chi-jiu-hua-yu-guan-bi&quot;&gt;持久化与关闭&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;SIGHUP&lt;&#x2F;code&gt;：执行一次检查点（刷新用量队列、落盘账号状态、Redis &lt;code&gt;SAVE&lt;&#x2F;code&gt;），服务不中断。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;code&gt;SIGTERM&lt;&#x2F;code&gt;&#x2F;&lt;code&gt;SIGINT&lt;&#x2F;code&gt;：停止接收新请求并等待在途请求（最多 20 秒），关闭 WebSocket 会话并等待结算，再执行最终检查点（最多 30 秒）。部署模板的 &lt;code&gt;stop_grace_period: 60s&lt;&#x2F;code&gt; 覆盖这两个阶段。&lt;&#x2F;li&gt;
&lt;li&gt;进程被强制终止（&lt;code&gt;SIGKILL&lt;&#x2F;code&gt;、OOM）时，在途请求不会结算。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;routing&#x2F;&quot;&gt;路由与故障转移&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;billing&#x2F;&quot;&gt;计费与价格&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;operations&#x2F;&quot;&gt;运维&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>计费与价格</title>
        <published>2026-11-19T00:00:00+08:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/concepts/billing/"/>
        <id>https://xsicontrol.com/docs/concepts/billing/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/concepts/billing/">&lt;p&gt;XSI 按上游返回的真实用量实时计费：Token、缓存、图片、视频秒数、音频时长、搜索与工具调用次数都可以单独定价。余额与扣费统一以**人民币（CNY）**计。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;jia-ge-cong-na-li-lai&quot;&gt;价格从哪里来&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;来源&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;api&#x2F;pricing.json&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;系统默认价格表，随镜像发布，启动时加载；修改后需重启&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;租户 &lt;code&gt;PRICING&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;租户通过 &lt;code&gt;&#x2F;x-config&lt;&#x2F;code&gt; 覆盖或新增模型价格，按模型整条替换，立即生效&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;&lt;code&gt;GET &#x2F;x-pricing&lt;&#x2F;code&gt; 可查看系统原价、租户覆盖后的价格以及账号最终的人民币价格，见《&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;pricing-api&#x2F;&quot;&gt;价格目录 API&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;bi-chong-yu-bei-lu&quot;&gt;币种与倍率&lt;&#x2F;h2&gt;
&lt;p&gt;价格表记录的是&lt;strong&gt;服务商原币种的原价&lt;&#x2F;strong&gt;，再通过倍率换算为人民币：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;扣费 = 原价 × 用量 × 模型 Rates ×（快速档位倍率，仅 Token 部分）× 账号 Rates × 账号 Factor&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;倍率&lt;&#x2F;th&gt;&lt;th&gt;设置者&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;模型 &lt;code&gt;Rates&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;价格表&lt;&#x2F;td&gt;&lt;td&gt;换算与加价系数。默认价格表中美元标价的模型为 &lt;code&gt;7&lt;&#x2F;code&gt;，人民币标价的模型为 &lt;code&gt;1&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;账号 &lt;code&gt;Rates&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;父账号&lt;&#x2F;td&gt;&lt;td&gt;子账号不低于父账号；父子之间的差价即父账号的分销收益&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;账号 &lt;code&gt;Factor&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;租户所有者&lt;&#x2F;td&gt;&lt;td&gt;价格系数，可用于不同客户或渠道的折扣与加价&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;费用只从调用账号自身的余额扣除，不沿祖先链逐级扣费。父账号的收益在为子账号划转额度时按 &lt;code&gt;子.Rates ÷ 父.Rates&lt;&#x2F;code&gt; 折算实现。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;jia-ge-biao-jie-gou&quot;&gt;价格表结构&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;json&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  &amp;quot;ChatPricing&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;    &amp;quot;gpt-6.2-sol&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;      &amp;quot;InputText&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 2&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;CachedText&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 0.1&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;CacheWrite&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 2.5&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;OutputText&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 10&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;      &amp;quot;FastTokenMultiplier&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 2&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;Rates&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 7&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;      &amp;quot;ContextTiers&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: [{&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;InputThreshold&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 272000&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;InputText&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 4&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;CachedText&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 0.2&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;CacheWrite&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 5&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;OutputText&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 15&lt;&#x2F;span&gt;&lt;span&gt;}]&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    }&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;  },&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  &amp;quot;ImgPricing&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;grok-imagine-image-quality&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;Sizes&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;1k&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 0.05&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;2k&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 0.07&lt;&#x2F;span&gt;&lt;span&gt;},&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;InputImage&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 0.01&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;Rates&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 7&lt;&#x2F;span&gt;&lt;span&gt;}},&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  &amp;quot;VideoPricing&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;grok-imagine-video&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;Resolutions&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;480p&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 0.05&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;720p&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 0.07&lt;&#x2F;span&gt;&lt;span&gt;},&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;InputImage&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 0.002&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;Rates&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 7&lt;&#x2F;span&gt;&lt;span&gt;}},&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  &amp;quot;AudioPricing&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;gpt-live-1&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;Unit&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;per_minute&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;Input&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 0.05&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;Rates&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 7&lt;&#x2F;span&gt;&lt;span&gt;}}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h3 id=&quot;dui-hua-mo-xing-chatpricing&quot;&gt;对话模型 &lt;code&gt;ChatPricing&lt;&#x2F;code&gt;&lt;&#x2F;h3&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;字段&lt;&#x2F;th&gt;&lt;th&gt;单位&lt;&#x2F;th&gt;&lt;th&gt;计费对象&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;InputText&lt;&#x2F;code&gt;、&lt;code&gt;InputAudio&lt;&#x2F;code&gt;、&lt;code&gt;InputImage&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每百万 Token&lt;&#x2F;td&gt;&lt;td&gt;未命中缓存的输入&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;CachedText&lt;&#x2F;code&gt;、&lt;code&gt;CachedAudio&lt;&#x2F;code&gt;、&lt;code&gt;CachedImage&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每百万 Token&lt;&#x2F;td&gt;&lt;td&gt;缓存读取（不重复计入输入）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;CacheWrite&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每百万 Token&lt;&#x2F;td&gt;&lt;td&gt;缓存写入&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;OutputText&lt;&#x2F;code&gt;、&lt;code&gt;OutputAudio&lt;&#x2F;code&gt;、&lt;code&gt;OutputImage&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每百万 Token&lt;&#x2F;td&gt;&lt;td&gt;输出&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;ReasonText&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每百万 Token&lt;&#x2F;td&gt;&lt;td&gt;推理 Token 单独计价；未设置时推理 Token 包含在输出中按 &lt;code&gt;OutputText&lt;&#x2F;code&gt; 计&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;Query&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每次&lt;&#x2F;td&gt;&lt;td&gt;联网搜索、&lt;code&gt;x_search&lt;&#x2F;code&gt;、代码执行等工具调用，DeepSeek 搜索与抓取&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;Find&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每次&lt;&#x2F;td&gt;&lt;td&gt;文件检索&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;Page&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每页&lt;&#x2F;td&gt;&lt;td&gt;文档页数&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SizeHigh&lt;&#x2F;code&gt;、&lt;code&gt;SizeMedium&lt;&#x2F;code&gt;、&lt;code&gt;SizeLow&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每次&lt;&#x2F;td&gt;&lt;td&gt;Responses 中按档位计费的工具调用&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;Call&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每次请求&lt;&#x2F;td&gt;&lt;td&gt;固定费用，以人民币计，不乘模型 &lt;code&gt;Rates&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;FastTokenMultiplier&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;倍数&lt;&#x2F;td&gt;&lt;td&gt;fast 档位的 Token 倍率（大于 1 时生效）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;ContextTiers&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;长上下文分档，见下文&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h3 id=&quot;qi-ta-fen-lei&quot;&gt;其他分类&lt;&#x2F;h3&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;分类&lt;&#x2F;th&gt;&lt;th&gt;计费方式&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;ImgPricing&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;(Sizes[尺寸] × 张数 + InputImage × 输入图数 + Call) × 倍率&lt;&#x2F;code&gt;；未配置的尺寸以 &lt;code&gt;Call&lt;&#x2F;code&gt; 作单张价，&lt;code&gt;grok-imagine&lt;&#x2F;code&gt; 系列取已配置的最高价&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;VideoPricing&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;(Resolutions[分辨率] × 秒数 + InputImage × 输入图数 + Call) × 倍率&lt;&#x2F;code&gt;；时长 1–15 秒，默认 6 秒，分辨率默认 &lt;code&gt;480p&lt;&#x2F;code&gt;，未知分辨率按最高价&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;AudioPricing&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;Unit: &quot;per_minute&quot;&lt;&#x2F;code&gt; 时按时长（秒级计费）；否则按 Token 或字符数&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;RerankPricing&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;按 Token&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;CallPricing&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每次请求固定价&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;FineTuningPricing&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;按 Token，适用于 &lt;code&gt;ft:&lt;&#x2F;code&gt; 模型&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;同时出现在 &lt;code&gt;ChatPricing&lt;&#x2F;code&gt; 中的图片模型（如 &lt;code&gt;gpt-image-2.6-*&lt;&#x2F;code&gt;）按 Token 计费。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;huan-cun&quot;&gt;缓存&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;缓存读取&lt;&#x2F;strong&gt;按 &lt;code&gt;Cached*&lt;&#x2F;code&gt; 单价单独计费，不再计入输入。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;Anthropic 缓存写入&lt;&#x2F;strong&gt;（&lt;code&gt;cache_creation_input_tokens&lt;&#x2F;code&gt;，含 5 分钟与 1 小时两种）按 &lt;code&gt;CacheWrite&lt;&#x2F;code&gt; 计费。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;OpenAI 缓存写入&lt;&#x2F;strong&gt;（&lt;code&gt;input_tokens_details.cache_write_tokens&lt;&#x2F;code&gt;）包含在输入内：30 分钟写入按 &lt;code&gt;CacheWrite&lt;&#x2F;code&gt;，12 小时写入按 2 × &lt;code&gt;CacheWrite&lt;&#x2F;code&gt;；模型未设置 &lt;code&gt;CacheWrite&lt;&#x2F;code&gt; 时按输入价。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;kuai-su-dang-wei&quot;&gt;快速档位&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;请求或响应中的值&lt;&#x2F;th&gt;&lt;th&gt;档位&lt;&#x2F;th&gt;&lt;th&gt;Token 倍率&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;speed: fast&lt;&#x2F;code&gt;，&lt;code&gt;service_tier: priority&lt;&#x2F;code&gt; 或 &lt;code&gt;fast&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;fast&lt;&#x2F;td&gt;&lt;td&gt;模型的 &lt;code&gt;FastTokenMultiplier&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;speed: ultrafast&lt;&#x2F;code&gt;，&lt;code&gt;service_tier: ultrafast&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;ultrafast&lt;&#x2F;td&gt;&lt;td&gt;6&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;default&lt;&#x2F;code&gt;、&lt;code&gt;standard&lt;&#x2F;code&gt;、&lt;code&gt;flex&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;标准&lt;&#x2F;td&gt;&lt;td&gt;1&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;以上游响应报告的档位为准；响应未报告时按请求值计费。倍率只作用于 Token 费用。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;chang-shang-xia-wen-fen-dang&quot;&gt;长上下文分档&lt;&#x2F;h2&gt;
&lt;p&gt;当一次请求的输入 Token 总数（含缓存读写）&lt;strong&gt;大于&lt;&#x2F;strong&gt;某档的 &lt;code&gt;InputThreshold&lt;&#x2F;code&gt; 时，该请求的&lt;strong&gt;全部&lt;&#x2F;strong&gt; Token 都按该档价格计费；档位中未设置的字段沿用基础价。例如 &lt;code&gt;gpt-6.2-sol&lt;&#x2F;code&gt; 输入超过 272000 Token 时，输入与输出单价分别变为 4 与 15。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;shen-me-hui-bei-ji-fei&quot;&gt;什么会被计费&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;情况&lt;&#x2F;th&gt;&lt;th&gt;计费&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;POST 请求，上游返回 &lt;code&gt;200&lt;&#x2F;code&gt;（视频创建为任意 2xx）&lt;&#x2F;td&gt;&lt;td&gt;按实际用量&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;流式请求中途断开&lt;&#x2F;td&gt;&lt;td&gt;按已生成的用量&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;上游响应缺少用量&lt;&#x2F;td&gt;&lt;td&gt;按输出内容与会话估算&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;GET、DELETE（查询结果、轮询视频、删除文件等）&lt;&#x2F;td&gt;&lt;td&gt;不计费&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;上游错误（非 200）&lt;&#x2F;td&gt;&lt;td&gt;不计费&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;被资源白名单拒绝的 POST，被模型白名单或模型级限额拒绝（&lt;code&gt;403&lt;&#x2F;code&gt;&#x2F;&lt;code&gt;429&lt;&#x2F;code&gt;）的 POST，请求体无法解析&lt;&#x2F;td&gt;&lt;td&gt;收取 &lt;code&gt;XAPI_FEE&lt;&#x2F;code&gt;（默认 ¥0.012）；账号级限速返回的 &lt;code&gt;429&lt;&#x2F;code&gt; 不收取&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;成功但模型不在价格表中&lt;&#x2F;td&gt;&lt;td&gt;收取 &lt;code&gt;XAPI_FEE&lt;&#x2F;code&gt;，并通知运营者&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;部分管理查询（见各接口说明）&lt;&#x2F;td&gt;&lt;td&gt;收取 &lt;code&gt;XAPI_FEE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;&lt;code&gt;XAPI_FEE&lt;&#x2F;code&gt; 以模型名 &lt;code&gt;XAPI&lt;&#x2F;code&gt; 出现在账单中，上限为 ¥0.24。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;e-du-yu-you-xiao-qi&quot;&gt;额度与有效期&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;余额由多笔&lt;strong&gt;额度&lt;&#x2F;strong&gt;组成，每笔额度有独立的金额、余额、来源说明与到期时间；可用余额为未过期额度之和。&lt;&#x2F;li&gt;
&lt;li&gt;有效期：管理员充值按 &lt;code&gt;Days&lt;&#x2F;code&gt;（默认且最长 365 天）；租户所有者创建子账号时发放的初始额度为 1 年（超过 1 亿时 100 年）；普通管理者划转的额度不晚于来源额度；注册赠金 1 个月；订阅额度按套餐周期。&lt;&#x2F;li&gt;
&lt;li&gt;额度分为&lt;strong&gt;按量&lt;&#x2F;strong&gt;与&lt;strong&gt;订阅&lt;&#x2F;strong&gt;两种资金类型。Role 3（订阅）账号优先使用订阅额度，订阅额度用尽后可自动改用按量余额。&lt;&#x2F;li&gt;
&lt;li&gt;扣费可使余额短暂为负，欠款记为负额度，后续入账优先抵扣。&lt;&#x2F;li&gt;
&lt;li&gt;余额低于 &lt;code&gt;USER_MIN_BALANCE − 0.01&lt;&#x2F;code&gt; 时账号被冻结（&lt;code&gt;429&lt;&#x2F;code&gt;），充值后自动恢复。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;pricing-api&#x2F;&quot;&gt;价格目录 API&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;tenant-config&#x2F;#pricing&quot;&gt;租户配置 API&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;access-control&#x2F;&quot;&gt;访问控制与限额&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>路由与故障转移</title>
        <published>2026-11-19T00:00:00+08:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/concepts/routing/"/>
        <id>https://xsicontrol.com/docs/concepts/routing/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/concepts/routing/">&lt;p&gt;XSI 的路由回答两个问题：&lt;strong&gt;请求发往哪个模型&lt;&#x2F;strong&gt;，以及&lt;strong&gt;由哪个上游 Key 承载&lt;&#x2F;strong&gt;。前者由模型映射决定，后者由 Level（Key 池分组）与调度策略决定。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;he-xin-dui-xiang&quot;&gt;核心对象&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;对象&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Provider Key&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;租户录入的上游 Key，带有 &lt;code&gt;Provider&lt;&#x2F;code&gt;（上游地址）、&lt;code&gt;Level&lt;&#x2F;code&gt;、启用状态等属性&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Level&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;Key 池分组编号。同一 Level 内的 Key 组成一个轮询池&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;MODEL_MAPPER&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;模型改写规则：&lt;code&gt;请求模型 → 上游模型&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;LEVEL_MAPPER&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;分组规则：&lt;code&gt;上游模型 → Level&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Gear&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;账号的路由模式，决定使用租户映射还是账号自身映射，以及能否跨组重试&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;典型配置：OpenAI Key 放在 Level 1，Anthropic Key 放在 Level 2，DeepSeek Key 放在 Level 3，再设置 &lt;code&gt;LEVEL_MAPPER = gpt*=1, claude*=2, deepseek*=3&lt;&#x2F;code&gt;。录入 Key 时 XSI 会按服务商自动补全这类映射。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;mo-xing-jie-xi&quot;&gt;模型解析&lt;&#x2F;h2&gt;
&lt;p&gt;请求模型按以下顺序解析，取第一个命中项：&lt;&#x2F;p&gt;
&lt;ol&gt;
&lt;li&gt;当前生效的模型故障替换（&lt;code&gt;MODEL_FAILOVER&lt;&#x2F;code&gt;，见下文）&lt;&#x2F;li&gt;
&lt;li&gt;账号级 &lt;code&gt;ModelMapper&lt;&#x2F;code&gt;：先精确，再通配&lt;&#x2F;li&gt;
&lt;li&gt;租户级 &lt;code&gt;MODEL_MAPPER&lt;&#x2F;code&gt;：先精确，再通配&lt;&#x2F;li&gt;
&lt;li&gt;模糊匹配：模型已在价格表中则原样使用；否则在&lt;strong&gt;同家族、同模态&lt;&#x2F;strong&gt;的已定价模型中选择版本最接近者（例如 &lt;code&gt;gpt-image-2.5-flare&lt;&#x2F;code&gt; → &lt;code&gt;gpt-image-2.6-flare&lt;&#x2F;code&gt;），&lt;code&gt;latest&lt;&#x2F;code&gt;、&lt;code&gt;preview&lt;&#x2F;code&gt;、日期快照等后缀被忽略&lt;&#x2F;li&gt;
&lt;li&gt;原样使用&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;p&gt;解析结果会&lt;strong&gt;真正改写&lt;&#x2F;strong&gt;发给上游的模型名（JSON 的 &lt;code&gt;model&lt;&#x2F;code&gt;、multipart 字段或 URL 中的模型），并缓存为账号级的精确映射，后续请求优先命中。因此通过 &lt;code&gt;PUT &#x2F;x-config&lt;&#x2F;code&gt; 修改租户映射后，已解析过该模型的账号会继续使用缓存结果；需要立即生效时，用 &lt;code&gt;POST &#x2F;x-conf&lt;&#x2F;code&gt; 的 &lt;code&gt;ModelMapper&lt;&#x2F;code&gt; 同步到后代。&lt;&#x2F;p&gt;
&lt;p&gt;&lt;strong&gt;通配规则&lt;&#x2F;strong&gt;：&lt;code&gt;*&lt;&#x2F;code&gt; 匹配任意字符，其余字符按字面匹配。多个通配同时命中时，优先选择字面后缀更靠近模型名末尾、后缀更长、前缀更长、字面总长更长、&lt;code&gt;*&lt;&#x2F;code&gt; 更少的模式。&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;MODEL_MAPPER = gpt-latest=gpt-6.2-sol, claude-*-latest=claude-sonnet-5-5&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;level-jie-xi&quot;&gt;Level 解析&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;账号 Gear&lt;&#x2F;th&gt;&lt;th&gt;Level 来源&lt;&#x2F;th&gt;&lt;th&gt;未命中时&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;Gear &amp;gt; 0&lt;&#x2F;code&gt;（跟随租户）&lt;&#x2F;td&gt;&lt;td&gt;租户 &lt;code&gt;LEVEL_MAPPER&lt;&#x2F;code&gt;：先精确，再通配（最长模式优先）&lt;&#x2F;td&gt;&lt;td&gt;账号自身的 Level&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;Gear ≤ 0&lt;&#x2F;code&gt;（独立）&lt;&#x2F;td&gt;&lt;td&gt;账号自身的 &lt;code&gt;LevelMapper&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;账号自身的 Level&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;新账号的 Gear 继承自父账号；root 与注册账号默认 &lt;code&gt;Gear = 1&lt;&#x2F;code&gt;，即跟随租户配置。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;key-xuan-ze&quot;&gt;Key 选择&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;每个租户的每个 Level 维护一个轮询环，跳过禁用与休眠中的 Key。&lt;&#x2F;li&gt;
&lt;li&gt;Responses、Chat Completions 与 Messages 请求使用&lt;strong&gt;粘性会话&lt;&#x2F;strong&gt;：同一会话固定到同一个 Key，以提高提示缓存命中率，并让 &lt;code&gt;GET &#x2F;v1&#x2F;responses&#x2F;{id}&lt;&#x2F;code&gt; 读到同一上游账号上的结果。会话标识依次取请求头 &lt;code&gt;session_id&lt;&#x2F;code&gt;、&lt;code&gt;conversation_id&lt;&#x2F;code&gt;，请求体 &lt;code&gt;prompt_cache_key&lt;&#x2F;code&gt;，请求头 &lt;code&gt;session-id&lt;&#x2F;code&gt;、&lt;code&gt;thread-id&lt;&#x2F;code&gt;；都没有时按“租户 + 账号 + Level”固定。绑定默认保留 24 小时（&lt;code&gt;STICKY_BINDING_TTL&lt;&#x2F;code&gt;）。&lt;&#x2F;li&gt;
&lt;li&gt;粘性调度默认对所有 Level 开启（&lt;code&gt;STICKY_SCHEDULER=true&lt;&#x2F;code&gt;）；设为 &lt;code&gt;false&lt;&#x2F;code&gt; 后只对租户 &lt;code&gt;STICKY_LEVELS&lt;&#x2F;code&gt; 中的 Level 开启。&lt;&#x2F;li&gt;
&lt;li&gt;视频轮询固定使用创建任务的 Key；DeepSeek 文件请求固定使用上传文件的 Key。&lt;&#x2F;li&gt;
&lt;li&gt;Level 中没有可用 Key 时返回 &lt;code&gt;500 No available key&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;zi-dong-zhong-shi&quot;&gt;自动重试&lt;&#x2F;h2&gt;
&lt;p&gt;重试发生在向客户端写出任何字节之前，对流式请求同样有效：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;项目&lt;&#x2F;th&gt;&lt;th&gt;规则&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;适用请求&lt;&#x2F;td&gt;&lt;td&gt;POST&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;触发状态&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;400 &amp;lt; status &amp;lt; 600&lt;&#x2F;code&gt; 且不在 &lt;code&gt;NO_RETRY_STATUS&lt;&#x2F;code&gt;（默认 &lt;code&gt;200,400,403,404,405,413,421,422,499,500&lt;&#x2F;code&gt;）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;同组重试&lt;&#x2F;td&gt;&lt;td&gt;当前 Level 内最多 7 次，避开最近一次失败的 Key（池中只有一个 Key 时可能重试同一个 Key）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;跨组重试&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;Gear ≤ 0&lt;&#x2F;code&gt; 的账号：在账号 &lt;code&gt;AllowLevels&lt;&#x2F;code&gt; 中的其他 Level 上各最多 3 次；&lt;code&gt;Gear &amp;gt; 0&lt;&#x2F;code&gt; 的账号不跨 &lt;code&gt;AllowLevels&lt;&#x2F;code&gt;，但可能在映射得到的 Level 与账号自身 Level 之间重试&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;例外&lt;&#x2F;td&gt;&lt;td&gt;Responses 创建返回 &lt;code&gt;400&lt;&#x2F;code&gt; 且提示 &lt;code&gt;not supported&lt;&#x2F;code&gt; 时，只在同组换 Key；视频创建永不重试&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;全部失败时，客户端收到首次失败的上游响应。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;key-xiu-mian-yu-sheng-ming-zhou-qi&quot;&gt;Key 休眠与生命周期&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;机制&lt;&#x2F;th&gt;&lt;th&gt;条件&lt;&#x2F;th&gt;&lt;th&gt;效果&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;自动休眠&lt;&#x2F;td&gt;&lt;td&gt;上游返回 &lt;code&gt;STATUS_CODES&lt;&#x2F;code&gt; 中的状态（默认 &lt;code&gt;429,401,402,503,408,524&lt;&#x2F;code&gt;）；同组多于 1 个 Key；Key 的 Level &amp;gt; 0；未设置 &lt;code&gt;NoSleep&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;退出轮询 &lt;code&gt;KEY_BACK&lt;&#x2F;code&gt; 分钟（默认 60）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;唤醒同伴&lt;&#x2F;td&gt;&lt;td&gt;同组仅剩的 Key 也失败&lt;&#x2F;td&gt;&lt;td&gt;唤醒同组中自动休眠的 Key，避免整组不可用&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;手动休眠&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;x-keys&#x2F;{id}&#x2F;sleep&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;32 小时&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;自动禁用&lt;&#x2F;td&gt;&lt;td&gt;上游返回 &lt;code&gt;AUTO_DISABLE_KEY_STATUS&lt;&#x2F;code&gt; 中的状态&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;Status=false&lt;&#x2F;code&gt;，直到手动启用&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;自动删除&lt;&#x2F;td&gt;&lt;td&gt;上游返回 &lt;code&gt;AUTO_DELETE_KEY_STATUS&lt;&#x2F;code&gt; 中的状态&lt;&#x2F;td&gt;&lt;td&gt;删除 Key&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;自动禁用与自动删除默认关闭，且不会作用于同组中最后一个启用的 Key。例如 &lt;code&gt;AUTO_DISABLE_KEY_STATUS=401&lt;&#x2F;code&gt; 可让被上游吊销的 Key 自动退出。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;fen-zu-qie-huan-yu-mo-xing-gu-zhang-ti-huan&quot;&gt;分组切换与模型故障替换&lt;&#x2F;h2&gt;
&lt;p&gt;当同一租户下同一模型的失败次数累计达到 &lt;code&gt;MODEL_FAILOVER_THRESHOLD&lt;&#x2F;code&gt;（代码默认 3，Compose 模板为 2）时触发；只要相邻两次失败的间隔不超过 1 分钟就持续累计，中间的成功请求不会清零：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;机制&lt;&#x2F;th&gt;&lt;th&gt;配置&lt;&#x2F;th&gt;&lt;th&gt;适用账号&lt;&#x2F;th&gt;&lt;th&gt;效果&lt;&#x2F;th&gt;&lt;th&gt;持续时间&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;分组切换&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;SWITCH_OVER = 1=3&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;Gear &amp;gt; 0&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;该模型在租户内临时改用目标 Level&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;SWITCH_OVER_TTL&lt;&#x2F;code&gt;（默认 1 小时）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;模型故障替换&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;MODEL_FAILOVER = gpt-6.2-sol=gpt-6.1-sol&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;未发生分组切换时&lt;&#x2F;td&gt;&lt;td&gt;对该账号临时把模型替换为备用模型（必须已定价），并通知运营者&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;MODEL_FAILOVER_TTL&lt;&#x2F;code&gt;（默认 1 小时）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;状态码在 &lt;code&gt;NO_RETRY_STATUS&lt;&#x2F;code&gt; 中的失败不计入。切换与替换状态保存在各实例内存中。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;pei-zhi-shi-li&quot;&gt;配置示例&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -X&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; PUT &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;x-config&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;LEVEL_MAPPER&amp;quot;: &amp;quot;gpt*=1, claude*=2, deepseek*=3&amp;quot;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;SWITCH_OVER&amp;quot;: &amp;quot;1=4&amp;quot;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;MODEL_FAILOVER&amp;quot;: &amp;quot;claude-opus-5-5=claude-sonnet-5-5&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;  }&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ul&gt;
&lt;li&gt;Level 1 放主力 OpenAI Key，Level 4 放备用（例如 Azure OpenAI），持续失败时自动切换。&lt;&#x2F;li&gt;
&lt;li&gt;Opus 持续失败时，受影响账号临时改用 Sonnet。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;admin-api&#x2F;&quot;&gt;Provider Key API&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;tenant-config&#x2F;&quot;&gt;租户配置 API&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;configuration&#x2F;&quot;&gt;配置参考&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>配置参考</title>
        <published>2026-11-19T00:00:00+08:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/deployment/configuration/"/>
        <id>https://xsicontrol.com/docs/deployment/configuration/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/deployment/configuration/">&lt;p&gt;XSI 的配置分为三层：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;层级&lt;&#x2F;th&gt;&lt;th&gt;位置&lt;&#x2F;th&gt;&lt;th&gt;生效方式&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;部署级&lt;&#x2F;td&gt;&lt;td&gt;API 与控制台容器的环境变量（本页）&lt;&#x2F;td&gt;&lt;td&gt;启动时读取一次，修改后需重启&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;租户级&lt;&#x2F;td&gt;&lt;td&gt;Redis 中的租户配置，通过 &lt;code&gt;&#x2F;x-config&lt;&#x2F;code&gt; 或配置管理控制台修改&lt;&#x2F;td&gt;&lt;td&gt;立即生效，自动同步到所有实例，见《&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;tenant-config&#x2F;&quot;&gt;租户配置 API&lt;&#x2F;a&gt;》&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;账号级&lt;&#x2F;td&gt;&lt;td&gt;账号记录，通过 &lt;code&gt;&#x2F;x-users&lt;&#x2F;code&gt; 或账户管理控制台修改&lt;&#x2F;td&gt;&lt;td&gt;立即生效，见《&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;manage-api&#x2F;&quot;&gt;账号管理 API&lt;&#x2F;a&gt;》&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;&lt;strong&gt;读取规则&lt;&#x2F;strong&gt;：环境变量只要存在就生效，即使是空字符串（例如 &lt;code&gt;EMAIL_SMTP: &quot;&quot;&lt;&#x2F;code&gt; 得到的是空值而不是默认值）。整数类变量无法解析或低于下限时使用默认值；时长类变量支持 &lt;code&gt;90m&lt;&#x2F;code&gt;、&lt;code&gt;2h&lt;&#x2F;code&gt; 或整数秒，低于下限时取下限；列表类变量用 &lt;code&gt;,&lt;&#x2F;code&gt; 或 &lt;code&gt;;&lt;&#x2F;code&gt; 分隔，&lt;strong&gt;不要在分隔符后加空格&lt;&#x2F;strong&gt;。&lt;&#x2F;p&gt;
&lt;p&gt;部分变量名以 &lt;code&gt;XAI_&lt;&#x2F;code&gt; 开头，这是历史命名，与 XSI 的功能一致。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;lian-jie-yu-chu-shi-hua&quot;&gt;连接与初始化&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;PORT&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;3443&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;HTTP 监听端口&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;POSTGRES_DSN&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;PostgreSQL 连接串（GORM 格式），连接失败时进程退出；首次启动自动建表与索引&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;REDIS_ADDR&lt;&#x2F;code&gt;、&lt;code&gt;REDIS_PASS&lt;&#x2F;code&gt;、&lt;code&gt;REDIS_DB&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—、—、&lt;code&gt;0&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;主 Redis&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;MAIL_REDIS_ADDR&lt;&#x2F;code&gt;、&lt;code&gt;MAIL_REDIS_PASS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;同主 Redis&lt;&#x2F;td&gt;&lt;td&gt;邮件队列与注册防刷使用的 Redis&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;MAIL_REDIS_DB&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;1&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;邮件队列 DB，最小为 1；须与邮件服务的 &lt;code&gt;REDIS_DB&lt;&#x2F;code&gt; 一致&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;INIT_USERS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;初始账号，格式 &lt;code&gt;名称::邮箱::Key&lt;&#x2F;code&gt;，多个用 &lt;code&gt;,&lt;&#x2F;code&gt; 分隔。只创建不存在的账号，不会更新已有账号。名为 &lt;code&gt;root&lt;&#x2F;code&gt; 的账号成为平台 root，应排在首位；Key 必须是 51 位 &lt;code&gt;sk-Xvs&lt;&#x2F;code&gt; 格式&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;bu-shu-mo-shi&quot;&gt;部署模式&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SINGLE_TENANT&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;true&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;true&lt;&#x2F;code&gt;：自助注册账号加入 root 租户；&lt;code&gt;false&lt;&#x2F;code&gt;：每个注册用户成为独立租户&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SINGLE_MODE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;true&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;true&lt;&#x2F;code&gt;：单实例，计数与通知在进程内；&lt;code&gt;false&lt;&#x2F;code&gt;：多实例，通过 Redis 共享。只有字面值 &lt;code&gt;false&lt;&#x2F;code&gt; 关闭&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;TRUSTED_PROXY_CIDRS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;回环地址与 RFC 1918 私网&lt;&#x2F;td&gt;&lt;td&gt;受信任的反向代理网段，只有来自这些地址的连接才读取转发头中的客户端 IP&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;TZ&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;镜像默认&lt;&#x2F;td&gt;&lt;td&gt;时区，决定日期统计、日额度与 RPD&#x2F;TPD 的切换时间&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;zhan-dian-di-zhi&quot;&gt;站点地址&lt;&#x2F;h2&gt;
&lt;p&gt;用于邮件内容、激活链接与控制台跳转。&lt;strong&gt;只写主机名&lt;&#x2F;strong&gt;，不要带协议或路径。&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_SVC&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;xsirouter.com&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;站点主域名&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_API&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;api.&amp;lt;XAI_SVC&amp;gt;&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;API 地址，激活链接为 &lt;code&gt;https:&#x2F;&#x2F;&amp;lt;XAI_API&amp;gt;&#x2F;x-sign&#x2F;activate&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_ADMIN&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;admin.&amp;lt;XAI_SVC&amp;gt;&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;配置管理控制台&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_MANAGE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;manage.&amp;lt;XAI_SVC&amp;gt;&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;账户管理控制台&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_DOCS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;docs.&amp;lt;XAI_SVC&amp;gt;&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;文档站&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_MAIL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;内置值&lt;&#x2F;td&gt;&lt;td&gt;平台通知收件人；租户未配置 &lt;code&gt;XAI_MAIL&lt;&#x2F;code&gt; 时使用。代码内置的默认收件人不属于你的组织，&lt;strong&gt;部署时必须设为自己的邮箱&lt;&#x2F;strong&gt;（在 Compose 模板中与 root 邮箱一同设置）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;QR_CODE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;默认客服二维码 URL&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;zhu-ce&quot;&gt;注册&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SIGN_ENABLE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;true&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;是否开放自助注册&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SAFE_ENABLE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;true&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;注册反滥用（按 IP 与邮箱的频率限制）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_CREDIT&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;单租户 &lt;code&gt;2&lt;&#x2F;code&gt;，多租户 &lt;code&gt;120&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;注册赠金（1 个月有效）；部署模板设为 &lt;code&gt;0&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_REFERRAL_REWARD_RATE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;0.05&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;推荐奖励比例，范围 0–0.1；&lt;code&gt;0&lt;&#x2F;code&gt; 关闭推荐码&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;zhang-hao-yu-ji-fei&quot;&gt;账号与计费&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;USER_FILTER&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;true&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;是否执行准入检查（IP、状态、额度、限速、白名单）与 &lt;code&gt;XAPI_FEE&lt;&#x2F;code&gt;。&lt;code&gt;false&lt;&#x2F;code&gt; 仅适合完全受信的内部环境，计费仍照常进行&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;USER_MIN_BALANCE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;1&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;冻结阈值（余额低于该值减 0.01 时冻结），也是新子账号的最低额度；下限 1&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;USER_API_BALANCE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;100&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;管理者权限所需的最低余额；下限 2&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAPI_FEE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;0.012&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;非模型类操作的固定手续费，上限 0.24&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;MONTHLY_USER_CREDIT&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;3000&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;订阅账号（Role 3）的默认每月额度单位；下限 100&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;STATS_INTERVAL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;1000&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;账号状态落盘频率：每 N 次请求同步 Redis，每 10N 次写 PostgreSQL；下限 10&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SYNC_ENABLE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;false&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每次请求都同步账号状态到 Redis（调试用，有性能开销）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;qing-qiu-yu-shang-you&quot;&gt;请求与上游&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;REQUEST_BODY_LIMIT_BYTES&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;209715200&lt;&#x2F;code&gt;（200 MiB）&lt;&#x2F;td&gt;&lt;td&gt;解压后的请求体上限；&lt;code&gt;0&lt;&#x2F;code&gt; 不限制&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;RESPONSE_HEADER_TIMEOUT_SECS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;1800&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;等待上游响应头的最长时间（秒）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;MASK_ERRORS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;false&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;用统一 JSON 替换所有 ≥ 400 的上游错误正文&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;LOG_ENABLE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;false&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;记录请求体日志（排障用，注意隐私）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;AZURE_AI_APIVERSION&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;Azure 的默认 &lt;code&gt;api-version&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;AZURE_AI_APIVERSION_CHAT&lt;&#x2F;code&gt;、&lt;code&gt;_RESPONSES&lt;&#x2F;code&gt;、&lt;code&gt;_EMBEDDINGS&lt;&#x2F;code&gt;、&lt;code&gt;_IMAGES&lt;&#x2F;code&gt;、&lt;code&gt;_AUDIO&lt;&#x2F;code&gt;、&lt;code&gt;_REALTIME&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;按接口类型指定 Azure &lt;code&gt;api-version&lt;&#x2F;code&gt;；Key 的 &lt;code&gt;config.api_versions&lt;&#x2F;code&gt; 优先&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;zhong-shi-xiu-mian-yu-gu-zhang-zhuan-yi&quot;&gt;重试、休眠与故障转移&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;NO_RETRY_STATUS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;200,400,403,404,405,413,421,422,499,500&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;不重试、也不计入模型失败的上游状态码&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;STATUS_CODES&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;429,401,402,503,408,524&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;触发 Key 自动休眠的上游状态码&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;KEY_BACK&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;60&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;自动休眠时长（分钟），下限 3&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;AUTO_DISABLE_KEY_STATUS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;触发 Key 自动禁用的状态码，例如 &lt;code&gt;401&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;AUTO_DELETE_KEY_STATUS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;触发 Key 自动删除的状态码；与上一项重复时删除优先&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;MODEL_FAILOVER_THRESHOLD&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;3&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;模型连续失败多少次触发分组切换或模型故障替换&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SWITCH_OVER_TTL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;1h&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;分组切换持续时间，下限 1 分钟&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;MODEL_FAILOVER_TTL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;1h&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;模型故障替换持续时间，下限 1 分钟&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;STICKY_SCHEDULER&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;true&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;全局粘性调度；&lt;code&gt;false&lt;&#x2F;code&gt; 时只对租户 &lt;code&gt;STICKY_LEVELS&lt;&#x2F;code&gt; 生效&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;STICKY_BINDING_TTL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;24h&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;会话与 Key 的绑定保留时间&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;websocket&quot;&gt;WebSocket&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;WS_MAX_CONN_DURATION&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;60m&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;单个 WebSocket 连接的最长时间，下限 5 分钟&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;WS_WRITE_TIMEOUT&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;15s&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;WebSocket 写超时，下限 3 秒&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;WS_DASHSCOPE_REALTIME_MAX_CONN_DURATION&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;120m&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;DashScope Realtime 连接最长时间&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;WS_RESPONSES_INITIAL_CONNECT_ATTEMPTS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;3&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;Responses WebSocket 首次连接上游时尝试的 Key 数&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;WS_RESPONSES_MAX_TURN_RETRIES&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;2&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;Responses WebSocket 每轮的重试次数&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;yong-liang-gu-suan-yu-wen-jian&quot;&gt;用量估算与文件&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SESSION_USAGE_TTL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;30m&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;会话最近一次真实用量的保留时间，用于估算中断请求的用量&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SESSION_USAGE_LIMIT&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;100000&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;上述缓存的条目上限&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;USAGE_ESTIMATE_ALERT_CREDIT&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;100&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;某账号当日估算计费达到该金额时记录告警日志&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;USAGE_ESTIMATE_ALERT_SHARE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;0.3&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;且估算部分占当日费用的比例不低于该值&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;FILE_REGISTRY_TTL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;3 年&lt;&#x2F;td&gt;&lt;td&gt;DeepSeek 文件归属登记的保留时间&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;you-jian&quot;&gt;邮件&lt;&#x2F;h2&gt;
&lt;p&gt;API 不直接连接 SMTP，而是把邮件写入 Redis 队列，由 &lt;code&gt;proxyxai&#x2F;mail&lt;&#x2F;code&gt; 服务投递。&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;EMAIL_SMTP&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_PORT&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_AUTH&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_PASS&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_SENDER&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;租户邮件配置的默认值。部署模板将 API 容器的 &lt;code&gt;EMAIL_SMTP&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_AUTH&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_PASS&lt;&#x2F;code&gt; 设为空字符串，由邮件服务统一投递；&lt;strong&gt;请勿依赖代码内置的默认值&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;EMAIL_FOOTER_YEAR&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;邮件页脚年份，默认当前年份&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;邮件服务（&lt;code&gt;xsirouter-mail&lt;&#x2F;code&gt;）的变量：&lt;code&gt;REDIS_ADDR&lt;&#x2F;code&gt;、&lt;code&gt;REDIS_DB&lt;&#x2F;code&gt;（&lt;code&gt;1&lt;&#x2F;code&gt;）、&lt;code&gt;EMAIL_SMTP&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_PORT&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_TLS&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_AUTH&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_PASS&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_WORKERS&lt;&#x2F;code&gt;、&lt;code&gt;REDIS_POP_TIMEOUT&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;kong-zhi-tai-rong-qi&quot;&gt;控制台容器&lt;&#x2F;h2&gt;
&lt;p&gt;控制台容器启动时把以下变量渲染为浏览器端的 &lt;code&gt;config.js&lt;&#x2F;code&gt;。未设置的变量为空。&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_API&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;API 地址；未设置时使用 &lt;code&gt;api.&amp;lt;当前主域&amp;gt;&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_ADMIN&lt;&#x2F;code&gt;、&lt;code&gt;XAI_MANAGE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;两个控制台互相跳转的地址&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;BRAND_NAME&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;控制台品牌名&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XPAY_API&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;支付网关租户地址，须包含 &lt;code&gt;&#x2F;t&#x2F;&amp;lt;tenant&amp;gt;&lt;&#x2F;code&gt;；为空时不启用钱包、商品与收入统计&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SUPPORT_QR_URL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;客服二维码&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_CARD_API&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;非空时品牌标识链接指向本站&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_HIDE_MODEL_PRICING&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;设为 &lt;code&gt;true&lt;&#x2F;code&gt; 时隐藏“模型与价格”链接&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_PLATFORM_MODE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;控制台展示模式&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_REFERRAL_REWARD_RATE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;前端显示的推荐奖励比例，应与 API 的同名变量一致&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;LICENSE_ID&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;商业授权编号，显示授权核验入口&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;jia-ge-biao&quot;&gt;价格表&lt;&#x2F;h2&gt;
&lt;p&gt;API 镜像在工作目录 &lt;code&gt;&#x2F;home&#x2F;nonroot&lt;&#x2F;code&gt; 中包含 &lt;code&gt;pricing.json&lt;&#x2F;code&gt;。以二进制方式运行时，请在 &lt;code&gt;pricing.json&lt;&#x2F;code&gt; 所在目录启动进程；文件缺失时 XSI 会退回一份内置的最小价格表，系统级模糊匹配失效（租户自定义的模型仍可参与匹配）。日常调价建议使用租户 &lt;code&gt;PRICING&lt;&#x2F;code&gt;，无需重启。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;docker-compose&#x2F;&quot;&gt;Docker Compose 部署&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;tenant-config&#x2F;&quot;&gt;租户配置 API&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;security&#x2F;&quot;&gt;安全加固&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>Docker Compose 部署</title>
        <published>2026-11-19T00:00:00+08:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/deployment/docker-compose/"/>
        <id>https://xsicontrol.com/docs/deployment/docker-compose/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/deployment/docker-compose/">&lt;p&gt;仓库提供的 &lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi&#x2F;blob&#x2F;main&#x2F;docker-compose.example.yml&quot;&gt;&lt;code&gt;docker-compose.example.yml&lt;&#x2F;code&gt;&lt;&#x2F;a&gt; 是一套完整的单机部署，全部配置都直接写在这一个文件里：API、两个控制台、邮件投递、PostgreSQL、Redis 以及两项每日备份。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;huan-jing-yao-qiu&quot;&gt;环境要求&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;项目&lt;&#x2F;th&gt;&lt;th&gt;要求&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;主机&lt;&#x2F;td&gt;&lt;td&gt;Linux x86_64，建议 2 核 4 GB 起&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;软件&lt;&#x2F;td&gt;&lt;td&gt;Docker、Docker Compose v2、Git、OpenSSL&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;网络&lt;&#x2F;td&gt;&lt;td&gt;可访问 Docker Hub、SMTP 服务器与所需的上游 API&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;域名&lt;&#x2F;td&gt;&lt;td&gt;API、配置管理、账户管理各一个，HTTPS 由反向代理提供&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;1-huo-qu-bu-shu-wen-jian&quot;&gt;1. 获取部署文件&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;git&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; clone https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi.git&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;cd&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; xsi&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;umask 077&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;cp&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; docker-compose.example.yml docker-compose.yml&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;sed&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -i&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;s&#x2F;CHANGE_ME_POSTGRES_PASSWORD&#x2F;$(&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;openssl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; rand&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -hex 24&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;)&#x2F;g&amp;quot; docker-compose.yml&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;sed&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -i&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;s&#x2F;CHANGE_ME_ROOT_KEY&#x2F;sk-Xvs$(&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;openssl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; rand&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -hex 24&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; |&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt; cut&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -c1-45&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;)&#x2F;&amp;quot; docker-compose.yml&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;两条 &lt;code&gt;sed&lt;&#x2F;code&gt; 命令分别生成数据库密码与 root 账号的 API Key。root Key 写在 &lt;code&gt;INIT_USERS&lt;&#x2F;code&gt; 中，必须恰好 &lt;strong&gt;51&lt;&#x2F;strong&gt; 个字符（&lt;code&gt;sk-Xvs&lt;&#x2F;code&gt; 前缀 6 位 + 45 位随机字符）。&lt;code&gt;docker-compose.yml&lt;&#x2F;code&gt; 与备份目录已被 &lt;code&gt;.gitignore&lt;&#x2F;code&gt; 排除。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;2-bian-ji-docker-compose-yml&quot;&gt;2. 编辑 &lt;code&gt;docker-compose.yml&lt;&#x2F;code&gt;&lt;&#x2F;h2&gt;
&lt;p&gt;需要修改的只有以下几处，其余保持模板值即可：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;位置&lt;&#x2F;th&gt;&lt;th&gt;配置&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;顶部 &lt;code&gt;x-site&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;XAI_SVC&lt;&#x2F;code&gt;、&lt;code&gt;XAI_API&lt;&#x2F;code&gt;、&lt;code&gt;XAI_ADMIN&lt;&#x2F;code&gt;、&lt;code&gt;XAI_MANAGE&lt;&#x2F;code&gt;、&lt;code&gt;XAI_DOCS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;站点、API、配置管理、账户管理与文档站的域名，&lt;strong&gt;只写主机名&lt;&#x2F;strong&gt;，不带协议、路径或 &lt;code&gt;&#x2F;v1&lt;&#x2F;code&gt;。API 与控制台两个服务共用这一处&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;顶部 &lt;code&gt;x-tz&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;时区&lt;&#x2F;td&gt;&lt;td&gt;默认 &lt;code&gt;Asia&#x2F;Shanghai&lt;&#x2F;code&gt;，影响日期统计与日额度的切换时间；如修改，请同步 &lt;code&gt;POSTGRES_DSN&lt;&#x2F;code&gt; 中的 &lt;code&gt;TimeZone&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-xsi&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;INIT_USERS&lt;&#x2F;code&gt;、&lt;code&gt;XAI_MAIL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;把 &lt;code&gt;admin@example.com&lt;&#x2F;code&gt; 换成你的 root 邮箱，它同时接收平台通知&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-xsi&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;TRUSTED_PROXY_CIDRS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;受信任的反向代理网段，见《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;》&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-xsi&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;SIGN_ENABLE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;是否开放自助注册，默认 &lt;code&gt;true&lt;&#x2F;code&gt;；开放前请先完成邮件配置&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-mail&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;EMAIL_SMTP&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_PORT&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_TLS&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_AUTH&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_PASS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;你的 SMTP 服务；&lt;code&gt;EMAIL_TLS: &quot;true&quot;&lt;&#x2F;code&gt; 对应隐式 TLS（通常为 465 端口）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-pages&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;BRAND_NAME&lt;&#x2F;code&gt;、&lt;code&gt;LICENSE_ID&lt;&#x2F;code&gt;、&lt;code&gt;XPAY_API&lt;&#x2F;code&gt;、&lt;code&gt;SUPPORT_QR_URL&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;控制台品牌名，以及可选的商业授权编号、支付网关地址（形如 &lt;code&gt;https:&#x2F;&#x2F;pay.example.com&#x2F;t&#x2F;my-tenant&lt;&#x2F;code&gt;）与客服二维码&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;备份服务&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;BACKUP_RETENTION_DAYS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;备份保留天数，默认 3&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;端口默认绑定 &lt;code&gt;127.0.0.1&lt;&#x2F;code&gt;，供同机反向代理访问；反向代理在其他主机时，改为可达的地址并配置访问控制。值中的 &lt;code&gt;$&lt;&#x2F;code&gt; 需写成 &lt;code&gt;$$&lt;&#x2F;code&gt;。完整的环境变量说明见《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;configuration&#x2F;&quot;&gt;配置参考&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;3-qi-dong&quot;&gt;3. 启动&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose config&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; --quiet&lt;&#x2F;span&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;   # 校验配置&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose up&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -d&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose ps&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; --fail&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; http:&#x2F;&#x2F;127.0.0.1:5443&#x2F;healthz&lt;&#x2F;span&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;   # 返回 OK&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;模板使用 &lt;code&gt;pull_policy: always&lt;&#x2F;code&gt;，每次启动都会拉取最新镜像。&lt;code&gt;&#x2F;healthz&lt;&#x2F;code&gt; 返回 &lt;code&gt;OK&lt;&#x2F;code&gt; 只表示 HTTP 服务已就绪；调用模型还需完成下文的上游配置。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;fu-wu-qing-dan&quot;&gt;服务清单&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;服务&lt;&#x2F;th&gt;&lt;th&gt;镜像&lt;&#x2F;th&gt;&lt;th&gt;端口&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-xsi&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;proxyxai&#x2F;xsi&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;5443&lt;&#x2F;code&gt; → &lt;code&gt;3443&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;API；停止宽限期 60 秒，文件描述符上限 1048576&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-pages&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;proxyxai&#x2F;xsi-pages&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;5080&lt;&#x2F;code&gt; → &lt;code&gt;8080&lt;&#x2F;code&gt;、&lt;code&gt;5081&lt;&#x2F;code&gt; → &lt;code&gt;8081&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;配置管理与账户管理控制台&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-mail&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;proxyxai&#x2F;mail&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;消费 Redis DB 1 的邮件队列并通过 SMTP 投递；停止宽限期 40 秒&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-postgres&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;postgres:18&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;业务数据，命名卷挂载至 &lt;code&gt;&#x2F;var&#x2F;lib&#x2F;postgresql&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-redis&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;redis:alpine&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;配置、缓存、用量与队列，命名卷挂载至 &lt;code&gt;&#x2F;data&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-postgres-backup&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;postgres:18&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;每日 &lt;code&gt;pg_dump&lt;&#x2F;code&gt; 至 &lt;code&gt;backups&#x2F;postgres&#x2F;&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-redis-backup&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;redis:alpine&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;—&lt;&#x2F;td&gt;&lt;td&gt;每日 RDB 快照至 &lt;code&gt;backups&#x2F;redis&#x2F;&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;PostgreSQL 与 Redis 只在 Compose 内部网络中可达，不发布主机端口。&lt;&#x2F;p&gt;
&lt;p&gt;模板为 API 固定设置了以下运行参数，可按需在 &lt;code&gt;docker-compose.yml&lt;&#x2F;code&gt; 中调整：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;变量&lt;&#x2F;th&gt;&lt;th&gt;模板值&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;USER_MIN_BALANCE&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;2&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;余额低于 1.99 时冻结调用&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;XAI_CREDIT&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;0&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;自助注册不赠送额度&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;MODEL_FAILOVER_THRESHOLD&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;2&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;模型连续失败 2 次触发分组切换或故障替换&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;EMAIL_SMTP&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_AUTH&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_PASS&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;空&lt;&#x2F;td&gt;&lt;td&gt;API 不设默认 SMTP，由邮件服务统一投递；租户可另配自有 SMTP&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;4-pei-zhi-https-ru-kou&quot;&gt;4. 配置 HTTPS 入口&lt;&#x2F;h2&gt;
&lt;p&gt;将三个域名解析到反向代理并配置证书：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;入口&lt;&#x2F;th&gt;&lt;th&gt;对外地址&lt;&#x2F;th&gt;&lt;th&gt;同机转发目标&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;API&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;https:&#x2F;&#x2F;api.example.com&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;http:&#x2F;&#x2F;127.0.0.1:5443&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;配置管理&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;https:&#x2F;&#x2F;admin.example.com&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;http:&#x2F;&#x2F;127.0.0.1:5080&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;账户管理&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;https:&#x2F;&#x2F;manage.example.com&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;http:&#x2F;&#x2F;127.0.0.1:5081&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;API 入口必须支持流式响应与 WebSocket 升级，Nginx 与 Caddy 示例见《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;》。控制台英文界面位于各自的 &lt;code&gt;&#x2F;en&#x2F;&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;5-jie-ru-shang-you-bing-chuang-jian-diao-yong-zhang-hao&quot;&gt;5. 接入上游并创建调用账号&lt;&#x2F;h2&gt;
&lt;ol&gt;
&lt;li&gt;打开配置管理控制台，使用 root Key（&lt;code&gt;INIT_USERS&lt;&#x2F;code&gt; 中的 &lt;code&gt;sk-Xvs...&lt;&#x2F;code&gt;）登录。&lt;&#x2F;li&gt;
&lt;li&gt;在“模型服务”中添加上游 Key，填写 Provider、SecretKey 与 Level，例如 OpenAI 放 Level 1、Anthropic 放 Level 2。XSI 会按服务商自动生成 &lt;code&gt;LEVEL_MAPPER&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;在“系统配置”中核对 &lt;code&gt;LEVEL_MAPPER&lt;&#x2F;code&gt;，按需设置 &lt;code&gt;MODEL_MAPPER&lt;&#x2F;code&gt;、&lt;code&gt;SWITCH_OVER&lt;&#x2F;code&gt; 等，见《&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;routing&#x2F;&quot;&gt;路由与故障转移&lt;&#x2F;a&gt;》。&lt;&#x2F;li&gt;
&lt;li&gt;核对 &lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi&#x2F;blob&#x2F;main&#x2F;api&#x2F;pricing.json&quot;&gt;默认价格表&lt;&#x2F;a&gt;，需要时通过租户 &lt;code&gt;PRICING&lt;&#x2F;code&gt; 覆盖。&lt;&#x2F;li&gt;
&lt;li&gt;在账户管理控制台创建实际调用用的子账号并分配额度，应用使用子账号的 Key。&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;div class=&quot;infobox&quot;&gt;
root Key 拥有平台的全部权限，只用于管理，不要用于日常模型调用或分发给应用。&lt;code&gt;INIT_USERS&lt;&#x2F;code&gt; 只创建尚不存在的账号；修改 &lt;code&gt;docker-compose.yml&lt;&#x2F;code&gt; 不会重置已有 root 的 Key，轮换请使用 &lt;code&gt;POST &#x2F;x-self&lt;&#x2F;code&gt;。
&lt;&#x2F;div&gt;
&lt;h2 id=&quot;6-yan-zheng&quot;&gt;6. 验证&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;https:&#x2F;&#x2F;api.example.com&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&amp;lt;子账号 Key&amp;gt;&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;dashboard&#x2F;status&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;chat&#x2F;completions&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;model&amp;quot;: &amp;quot;gpt-6.2-sol&amp;quot;, &amp;quot;messages&amp;quot;: [{&amp;quot;role&amp;quot;: &amp;quot;user&amp;quot;, &amp;quot;content&amp;quot;: &amp;quot;Hello&amp;quot;}]}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;duo-zu-hu-yu-duo-shi-li&quot;&gt;多租户与多实例&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;需求&lt;&#x2F;th&gt;&lt;th&gt;设置&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;自助注册用户成为独立租户（自带上游 Key）&lt;&#x2F;td&gt;&lt;td&gt;API 环境变量 &lt;code&gt;SINGLE_TENANT=false&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;多个 API 实例横向扩展&lt;&#x2F;td&gt;&lt;td&gt;所有实例共享同一 PostgreSQL 与 Redis，并设置 &lt;code&gt;SINGLE_MODE=false&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;多实例部署时，所有 API 实例共享同一 PostgreSQL 与 Redis，并在每个 API 容器的 &lt;code&gt;environment&lt;&#x2F;code&gt; 中显式设置 &lt;code&gt;SINGLE_MODE: &quot;false&quot;&lt;&#x2F;code&gt;（模板默认不传递该变量）；粘性绑定、限速计数与变更通知随即通过 Redis 共享。在同一主机上扩容前，需移除模板中固定的 &lt;code&gt;container_name&lt;&#x2F;code&gt; 与 &lt;code&gt;5443&lt;&#x2F;code&gt; 端口映射。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;configuration&#x2F;&quot;&gt;配置参考&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;operations&#x2F;&quot;&gt;运维&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;security&#x2F;&quot;&gt;安全加固&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>运维</title>
        <published>2026-11-19T00:00:00+08:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/deployment/operations/"/>
        <id>https://xsicontrol.com/docs/deployment/operations/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/deployment/operations/">&lt;h2 id=&quot;jian-kang-jian-cha&quot;&gt;健康检查&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; --fail&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; http:&#x2F;&#x2F;127.0.0.1:5443&#x2F;healthz&lt;&#x2F;span&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;   # 200 OK&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;&lt;code&gt;&#x2F;healthz&lt;&#x2F;code&gt; 无需认证，适合负载均衡器与容器编排的存活探针。它只反映 HTTP 服务是否就绪，不检查上游可用性。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;sheng-ji&quot;&gt;升级&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose pull&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose up&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -d&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose ps&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ul&gt;
&lt;li&gt;模板的 &lt;code&gt;pull_policy: always&lt;&#x2F;code&gt; 会在 &lt;code&gt;up&lt;&#x2F;code&gt; 时拉取最新镜像；需要固定版本时，把镜像改为具体标签（如 &lt;code&gt;proxyxai&#x2F;xsi:&amp;lt;version&amp;gt;&lt;&#x2F;code&gt;）并去掉 &lt;code&gt;pull_policy&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;数据库结构在 API 启动时自动迁移（GORM AutoMigrate）；三个大表索引以 &lt;code&gt;CREATE INDEX CONCURRENTLY&lt;&#x2F;code&gt; 创建，其余迁移仍可能短暂持锁，建议在低峰期升级。&lt;&#x2F;li&gt;
&lt;li&gt;升级前建议先执行一次检查点（见下文）并确认最近的备份可用。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;jian-cha-dian-yu-you-ya-guan-bi&quot;&gt;检查点与优雅关闭&lt;&#x2F;h2&gt;
&lt;p&gt;XSI 的余额与用量先在内存中累计，按批次写入 Redis 与 PostgreSQL。以下信号确保数据安全落盘：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;信号&lt;&#x2F;th&gt;&lt;th&gt;行为&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SIGHUP&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;立即执行一次检查点：刷新用量队列、落盘账号状态、Redis &lt;code&gt;SAVE&lt;&#x2F;code&gt;。服务不中断&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SIGTERM&lt;&#x2F;code&gt;、&lt;code&gt;SIGINT&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;停止接收新请求，等待在途 HTTP 请求（最多 20 秒），关闭 WebSocket 会话并等待结算，再执行最终检查点（最多 30 秒）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;SIGKILL&lt;&#x2F;code&gt;、OOM&lt;&#x2F;td&gt;&lt;td&gt;在途请求不会结算，最近一个检查点之后的内存数据可能丢失&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; kill&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; --signal=HUP&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; xsirouter-xsi&lt;&#x2F;span&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;     # 手动检查点&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose stop xsirouter-xsi&lt;&#x2F;span&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;          # 优雅关闭（宽限期 60 秒）&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;此外，XSI 每 2 小时 15 分钟自动执行一次完整的缓存落盘；也可以由租户所有者调用 &lt;code&gt;POST &#x2F;x-conf {&quot;SaveCache&quot;: true}&lt;&#x2F;code&gt; 触发。&lt;&#x2F;p&gt;
&lt;div class=&quot;infobox&quot;&gt;
请保留模板中的 &lt;code&gt;stop_grace_period: 60s&lt;&#x2F;code&gt;，并确保容器编排平台给予足够的终止宽限期，避免强制终止造成结算丢失。
&lt;&#x2F;div&gt;
&lt;h2 id=&quot;bei-fen&quot;&gt;备份&lt;&#x2F;h2&gt;
&lt;p&gt;模板包含两个备份服务，启动后立即执行一次，之后每 86400 秒执行一次：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;服务&lt;&#x2F;th&gt;&lt;th&gt;方式&lt;&#x2F;th&gt;&lt;th&gt;输出&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-postgres-backup&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;pg_dump&lt;&#x2F;code&gt; + gzip&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;backups&#x2F;postgres&#x2F;&amp;lt;时间戳&amp;gt;.sql.gz&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;xsirouter-redis-backup&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;redis-cli --rdb&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;backups&#x2F;redis&#x2F;&amp;lt;时间戳&amp;gt;.rdb&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;ul&gt;
&lt;li&gt;备份成功后才把临时文件重命名为正式文件；失败时可能留下 &lt;code&gt;.tmp&lt;&#x2F;code&gt; 文件，需要手动清理。&lt;&#x2F;li&gt;
&lt;li&gt;按 &lt;code&gt;find -mtime +N&lt;&#x2F;code&gt; 清理，&lt;code&gt;N&lt;&#x2F;code&gt; 为 &lt;code&gt;BACKUP_RETENTION_DAYS&lt;&#x2F;code&gt;（默认 3，按整天计）。&lt;&#x2F;li&gt;
&lt;li&gt;备份保存在宿主机的 &lt;code&gt;backups&#x2F;&lt;&#x2F;code&gt; 目录，&lt;strong&gt;请另行复制到异机或对象存储&lt;&#x2F;strong&gt;。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;Redis 中保存着租户配置、用量统计与 DeepSeek 文件登记，与 PostgreSQL 同等重要，两者都需要备份。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;hui-fu&quot;&gt;恢复&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose stop xsirouter-xsi xsirouter-mail&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;# PostgreSQL&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;gunzip&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -c&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; backups&#x2F;postgres&#x2F;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;&amp;lt;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;时间&lt;&#x2F;span&gt;&lt;span&gt;戳&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;&amp;gt;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;.sql.gz&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; |&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;  docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; exec&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -i&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; xsirouter-postgres psql&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -U&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; postgres&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; postgres&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;# Redis：停止 Redis，替换 RDB 后再启动&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose stop xsirouter-redis&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; run&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; --rm -v&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; xsi_redis_data:&#x2F;data&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -v&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$PWD&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;backups&#x2F;redis:&#x2F;backups&amp;quot; alpine&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;  cp &#x2F;backups&#x2F;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;&amp;lt;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;时间&lt;&#x2F;span&gt;&lt;span&gt;戳&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;&amp;gt;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;.rdb &#x2F;data&#x2F;dump.rdb&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose up&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -d&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;命名卷的实际名称以 &lt;code&gt;docker volume ls&lt;&#x2F;code&gt; 为准。恢复 PostgreSQL 前，如需全新恢复，请先清空目标数据库。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;shu-ju-cun-chu&quot;&gt;数据存储&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;数据&lt;&#x2F;th&gt;&lt;th&gt;位置&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;PostgreSQL&lt;&#x2F;td&gt;&lt;td&gt;命名卷挂载至 &lt;code&gt;&#x2F;var&#x2F;lib&#x2F;postgresql&lt;&#x2F;code&gt;，数据目录为 &lt;code&gt;&#x2F;var&#x2F;lib&#x2F;postgresql&#x2F;18&#x2F;docker&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Redis&lt;&#x2F;td&gt;&lt;td&gt;命名卷挂载至 &lt;code&gt;&#x2F;data&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;删除容器不会删除命名卷；&lt;code&gt;docker compose down -v&lt;&#x2F;code&gt; 会删除卷中的全部数据。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;ri-zhi&quot;&gt;日志&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose logs&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -f&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; xsirouter-xsi&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose logs&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -f&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; xsirouter-mail&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ul&gt;
&lt;li&gt;API 日志包含启动、检查点、上游异常与告警信息。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;code&gt;LOG_ENABLE=true&lt;&#x2F;code&gt;（或租户所有者 &lt;code&gt;POST &#x2F;x-conf {&quot;LogEnable&quot;: true}&lt;&#x2F;code&gt;）会记录请求体，仅在排障时短时开启。&lt;&#x2F;li&gt;
&lt;li&gt;账号级的管理操作日志可通过 &lt;code&gt;GET &#x2F;dashboard&#x2F;logs&lt;&#x2F;code&gt; 查看。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;heng-xiang-kuo-zhan&quot;&gt;横向扩展&lt;&#x2F;h2&gt;
&lt;ol&gt;
&lt;li&gt;所有 API 实例连接同一个 PostgreSQL 与 Redis。&lt;&#x2F;li&gt;
&lt;li&gt;设置 &lt;code&gt;SINGLE_MODE=false&lt;&#x2F;code&gt;，使限速计数、粘性绑定、Key 与账号变更通知通过 Redis 共享。&lt;&#x2F;li&gt;
&lt;li&gt;在负载均衡器后运行多个实例；不需要会话保持，粘性会话由 XSI 自身保证。&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;p&gt;多实例模式下，分组切换、模型故障替换与 Key 自动休眠仍由各实例独立判断。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;rong-liang-jian-yi&quot;&gt;容量建议&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;单个 API 实例即可承载大量并发流式连接；文件描述符上限应保持在模板的 1048576。&lt;&#x2F;li&gt;
&lt;li&gt;PostgreSQL 负载主要来自账号与 Key 的读写，用量明细保存在 Redis；Redis 内存随账号数与统计天数增长。&lt;&#x2F;li&gt;
&lt;li&gt;上游连接复用依赖 keep-alive，避免在 API 与上游之间加入会关闭空闲连接的中间设备。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;docker-compose&#x2F;&quot;&gt;Docker Compose 部署&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;architecture&#x2F;&quot;&gt;架构&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;security&#x2F;&quot;&gt;安全加固&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>反向代理</title>
        <published>2026-11-19T00:00:00+08:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/deployment/reverse-proxy/"/>
        <id>https://xsicontrol.com/docs/deployment/reverse-proxy/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/deployment/reverse-proxy/">&lt;p&gt;XSI 本身只提供 HTTP，HTTPS 由前置反向代理负责。API 入口对代理有三项要求：&lt;&#x2F;p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;不缓冲流式响应&lt;&#x2F;strong&gt;：SSE 需要逐块转发。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;支持 WebSocket 升级&lt;&#x2F;strong&gt;：Responses WebSocket、Realtime、Live 与 DeepSeek 语音合成都依赖它。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;足够长的超时&lt;&#x2F;strong&gt;：长推理与长连接可持续数十分钟。&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;p&gt;此外，代理需要把真实客户端 IP 传给 XSI，用于 IP 白名单、认证失败封禁与注册防刷。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;zhen-shi-ke-hu-duan-ip&quot;&gt;真实客户端 IP&lt;&#x2F;h2&gt;
&lt;p&gt;XSI 只在连接来自 &lt;code&gt;TRUSTED_PROXY_CIDRS&lt;&#x2F;code&gt;（默认回环地址与 RFC 1918 私网）时才读取转发头：先从 &lt;code&gt;X-Forwarded-For&lt;&#x2F;code&gt; 自右向左取第一个不受信任的地址，再依次查看 &lt;code&gt;CF-Connecting-IP&lt;&#x2F;code&gt;、&lt;code&gt;True-Client-IP&lt;&#x2F;code&gt;、&lt;code&gt;X-Real-IP&lt;&#x2F;code&gt;。来自其他地址的连接直接使用对端 IP。&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;代理与 XSI 同机或位于同一私网时，保持默认值即可。&lt;&#x2F;li&gt;
&lt;li&gt;代理位于公网其他地址时，把它的地址加入 &lt;code&gt;TRUSTED_PROXY_CIDRS&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;不要&lt;&#x2F;strong&gt;把任意公网网段加入受信列表，否则客户端可以伪造 IP。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;XSI 在转发到上游前会删除全部客户端 IP 相关的头，上游看不到终端用户的地址。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;nginx&quot;&gt;Nginx&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;nginx&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;map&lt;&#x2F;span&gt;&lt;span&gt; $&lt;&#x2F;span&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt;http_upgrade&lt;&#x2F;span&gt;&lt;span&gt; $connection_upgrade {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;    default&lt;&#x2F;span&gt;&lt;span&gt; upgrade;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;#39;&amp;#39;      &amp;#39;&amp;#39;&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;upstream&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt; xsi_api &lt;&#x2F;span&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    server&lt;&#x2F;span&gt;&lt;span&gt; 127.0.0.1:5443;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    keepalive&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 256&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;server&lt;&#x2F;span&gt;&lt;span&gt; {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    listen&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 443&lt;&#x2F;span&gt;&lt;span&gt; ssl;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    http2&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; on&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    server_name&lt;&#x2F;span&gt;&lt;span&gt; api.example.com;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    ssl_certificate&lt;&#x2F;span&gt;&lt;span&gt;     &#x2F;etc&#x2F;nginx&#x2F;certs&#x2F;api.example.com.crt;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    ssl_certificate_key&lt;&#x2F;span&gt;&lt;span&gt; &#x2F;etc&#x2F;nginx&#x2F;certs&#x2F;api.example.com.key;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    client_max_body_size&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 200m&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    underscores_in_headers&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; on&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;   # 保留 session_id、conversation_id 等粘性会话请求头&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    location&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt; &#x2F; &lt;&#x2F;span&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;        # CORS：控制台与浏览器应用跨域调用 API 时需要&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        if&lt;&#x2F;span&gt;&lt;span&gt; ($request_method&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; = &lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;#39;OPTIONS&amp;#39;&lt;&#x2F;span&gt;&lt;span&gt;) {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;            add_header&lt;&#x2F;span&gt;&lt;span&gt; Access-Control-Allow-Origin  &lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;#39;*&amp;#39;&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;            add_header&lt;&#x2F;span&gt;&lt;span&gt; Access-Control-Allow-Methods &lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;#39;GET, POST, PUT, DELETE, OPTIONS&amp;#39;&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;            add_header&lt;&#x2F;span&gt;&lt;span&gt; Access-Control-Allow-Headers &lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;#39;Authorization, Content-Type, X-Api-Key, X-Goog-Api-Key, Anthropic-Version, Anthropic-Beta, OpenAI-Beta, OpenAI-Organization, OpenAI-Project, Session_Id, Conversation_Id, Idempotency-Key&amp;#39;&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;            add_header&lt;&#x2F;span&gt;&lt;span&gt; Access-Control-Max-Age &lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;1728000&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;            add_header&lt;&#x2F;span&gt;&lt;span&gt; Content-Length &lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;0&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;            return&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 204&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;        }&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        add_header&lt;&#x2F;span&gt;&lt;span&gt; Access-Control-Allow-Origin  &lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;#39;*&amp;#39;&lt;&#x2F;span&gt;&lt;span&gt; always;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        add_header&lt;&#x2F;span&gt;&lt;span&gt; Access-Control-Allow-Methods &lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;#39;GET, POST, PUT, DELETE, OPTIONS&amp;#39;&lt;&#x2F;span&gt;&lt;span&gt; always;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        add_header&lt;&#x2F;span&gt;&lt;span&gt; Access-Control-Allow-Headers &lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;#39;Authorization, Content-Type, X-Api-Key, X-Goog-Api-Key, Anthropic-Version, Anthropic-Beta, OpenAI-Beta, OpenAI-Organization, OpenAI-Project, Session_Id, Conversation_Id, Idempotency-Key&amp;#39;&lt;&#x2F;span&gt;&lt;span&gt; always;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_pass&lt;&#x2F;span&gt;&lt;span&gt; http:&#x2F;&#x2F;xsi_api;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_http_version&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 1.1&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_set_header&lt;&#x2F;span&gt;&lt;span&gt; Host              $host;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_set_header&lt;&#x2F;span&gt;&lt;span&gt; X-Real-IP         $remote_addr;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_set_header&lt;&#x2F;span&gt;&lt;span&gt; X-Forwarded-For   $proxy_add_x_forwarded_for;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_set_header&lt;&#x2F;span&gt;&lt;span&gt; X-Forwarded-Proto $scheme;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;        # WebSocket&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_set_header&lt;&#x2F;span&gt;&lt;span&gt; Upgrade    $http_upgrade;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_set_header&lt;&#x2F;span&gt;&lt;span&gt; Connection $connection_upgrade;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;        # 流式响应&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_buffering&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;         off&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_request_buffering&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; off&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;        # 长推理与长连接&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_connect_timeout&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 10s&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_send_timeout&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;    3600s&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_read_timeout&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;    3600s&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    }&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;server&lt;&#x2F;span&gt;&lt;span&gt; {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    listen&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 443&lt;&#x2F;span&gt;&lt;span&gt; ssl;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    http2&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; on&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    server_name&lt;&#x2F;span&gt;&lt;span&gt; admin.example.com;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    ssl_certificate&lt;&#x2F;span&gt;&lt;span&gt;     &#x2F;etc&#x2F;nginx&#x2F;certs&#x2F;admin.example.com.crt;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    ssl_certificate_key&lt;&#x2F;span&gt;&lt;span&gt; &#x2F;etc&#x2F;nginx&#x2F;certs&#x2F;admin.example.com.key;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    location&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt; &#x2F; &lt;&#x2F;span&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_pass&lt;&#x2F;span&gt;&lt;span&gt; http:&#x2F;&#x2F;127.0.0.1:5080;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_set_header&lt;&#x2F;span&gt;&lt;span&gt; Host $host;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    }&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;server&lt;&#x2F;span&gt;&lt;span&gt; {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    listen&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 443&lt;&#x2F;span&gt;&lt;span&gt; ssl;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    http2&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; on&lt;&#x2F;span&gt;&lt;span&gt;;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    server_name&lt;&#x2F;span&gt;&lt;span&gt; manage.example.com;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    ssl_certificate&lt;&#x2F;span&gt;&lt;span&gt;     &#x2F;etc&#x2F;nginx&#x2F;certs&#x2F;manage.example.com.crt;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    ssl_certificate_key&lt;&#x2F;span&gt;&lt;span&gt; &#x2F;etc&#x2F;nginx&#x2F;certs&#x2F;manage.example.com.key;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;    location&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt; &#x2F; &lt;&#x2F;span&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_pass&lt;&#x2F;span&gt;&lt;span&gt; http:&#x2F;&#x2F;127.0.0.1:5081;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;        proxy_set_header&lt;&#x2F;span&gt;&lt;span&gt; Host $host;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    }&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;要点：&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;CORS 由代理提供&lt;&#x2F;strong&gt;。XSI 不发送 &lt;code&gt;Access-Control-Allow-*&lt;&#x2F;code&gt; 响应头，除 &lt;code&gt;&#x2F;x-pricing&lt;&#x2F;code&gt; 外也不处理 &lt;code&gt;OPTIONS&lt;&#x2F;code&gt; 预检；控制台运行在独立域名上，必须由代理直接以 &lt;code&gt;204&lt;&#x2F;code&gt; 应答预检并附加 CORS 头，否则控制台无法登录。分页响应头的暴露（&lt;code&gt;Access-Control-Expose-Headers&lt;&#x2F;code&gt;）由 XSI 自行设置。如需收紧，可把 &lt;code&gt;Access-Control-Allow-Origin&lt;&#x2F;code&gt; 改为控制台域名。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;code&gt;client_max_body_size&lt;&#x2F;code&gt; 应不小于 &lt;code&gt;REQUEST_BODY_LIMIT_BYTES&lt;&#x2F;code&gt;（默认 200 MiB）。&lt;&#x2F;li&gt;
&lt;li&gt;若为不同路径拆分了多个 &lt;code&gt;location&lt;&#x2F;code&gt;，每个承载 WebSocket 的路径（&lt;code&gt;&#x2F;v1&#x2F;responses&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;realtime&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;live&#x2F;&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;tools&#x2F;tts&lt;&#x2F;code&gt;）都需要带上 &lt;code&gt;Upgrade&lt;&#x2F;code&gt; 与 &lt;code&gt;Connection&lt;&#x2F;code&gt; 头。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;code&gt;Connection&lt;&#x2F;code&gt; 头使用 map 写法：有 &lt;code&gt;Upgrade&lt;&#x2F;code&gt; 时转发 WebSocket 升级，没有时发送空值，保持与上游的 keep-alive 连接复用。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code&gt;underscores_in_headers on&lt;&#x2F;code&gt; 不可省略&lt;&#x2F;strong&gt;。Nginx 默认丢弃名称带下划线的请求头，&lt;code&gt;session_id&lt;&#x2F;code&gt;、&lt;code&gt;conversation_id&lt;&#x2F;code&gt; 会因此丢失，粘性会话与提示缓存命中率随之下降。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;caddy&quot;&gt;Caddy&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;api.example.com {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    reverse_proxy 127.0.0.1:5443 {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;        flush_interval -1&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;        transport http {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;            read_timeout  3600s&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;            write_timeout 3600s&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;        }&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    }&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;admin.example.com {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    reverse_proxy 127.0.0.1:5080&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;manage.example.com {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    reverse_proxy 127.0.0.1:5081&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;Caddy 自动申请证书、透传 WebSocket，并默认设置 &lt;code&gt;X-Forwarded-For&lt;&#x2F;code&gt;。控制台跨域访问所需的 CORS 头与 &lt;code&gt;OPTIONS&lt;&#x2F;code&gt; 预检应答，请参照上面的 Nginx 示例用 &lt;code&gt;header&lt;&#x2F;code&gt; 与 &lt;code&gt;respond&lt;&#x2F;code&gt; 指令补充。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;cdn-yu-cloudflare&quot;&gt;CDN 与 Cloudflare&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;经过 Cloudflare 等 CDN 时，确保 CDN 回源地址或其网段在 &lt;code&gt;TRUSTED_PROXY_CIDRS&lt;&#x2F;code&gt; 内（或由同机代理统一处理），XSI 会读取 &lt;code&gt;CF-Connecting-IP&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;CDN 的响应超时可能短于长推理所需时间（例如 Cloudflare 免费套餐的 100 秒），超过时客户端会收到 &lt;code&gt;524&lt;&#x2F;code&gt;。长时间请求建议使用流式响应，或让 API 域名绕过 CDN 代理。&lt;&#x2F;li&gt;
&lt;li&gt;不要在 CDN 上缓存 API 响应。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;kong-zhi-tai&quot;&gt;控制台&lt;&#x2F;h2&gt;
&lt;p&gt;两个控制台是纯静态站点，容器内的 Nginx 已配置好缓存策略（HTML 与 &lt;code&gt;config.js&lt;&#x2F;code&gt; 不缓存，带版本号的 JS&#x2F;CSS 缓存一年），前置代理只需透传。控制台在浏览器中直接调用 API 域名，因此 API 入口必须提供上文的 CORS 配置。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;yan-zheng&quot;&gt;验证&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;# 流式：应逐块输出，而非最后一次性返回&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -N&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;https:&#x2F;&#x2F;api.example.com&#x2F;v1&#x2F;chat&#x2F;completions&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;model&amp;quot;:&amp;quot;gpt-6.2-sol&amp;quot;,&amp;quot;stream&amp;quot;:true,&amp;quot;messages&amp;quot;:[{&amp;quot;role&amp;quot;:&amp;quot;user&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;数到 20&amp;quot;}]}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;# WebSocket：应返回 101 Switching Protocols&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -i -N&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;https:&#x2F;&#x2F;api.example.com&#x2F;v1&#x2F;responses&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Connection: Upgrade&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Upgrade: websocket&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Sec-WebSocket-Version: 13&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Sec-WebSocket-Key: $(&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;openssl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; rand&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -base64 16&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;)&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;docker-compose&#x2F;&quot;&gt;Docker Compose 部署&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;realtime&#x2F;&quot;&gt;WebSocket 与实时接口&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;security&#x2F;&quot;&gt;安全加固&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>安全加固</title>
        <published>2026-11-19T00:00:00+08:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/deployment/security/"/>
        <id>https://xsicontrol.com/docs/deployment/security/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/deployment/security/">&lt;h2 id=&quot;nei-zhi-de-an-quan-ji-zhi&quot;&gt;内置的安全机制&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;机制&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;上游 Key 加密存储&lt;&#x2F;td&gt;&lt;td&gt;每个租户一把随机租户密钥，以 XChaCha20-Poly1305 加密上游 Key 与 Vertex 私钥；租户密钥再由账号自己的 API Key 加密&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;凭证隔离&lt;&#x2F;td&gt;&lt;td&gt;应用只持有 XSI Key；转发前剥离调用方的全部凭证与客户端 IP 头，上游 Key 不会返回给普通账号&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;认证防护&lt;&#x2F;td&gt;&lt;td&gt;按 IP 统计认证失败并临时封禁，无效 Key 负缓存&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;准入流水线&lt;&#x2F;td&gt;&lt;td&gt;IP、状态、额度、限速、资源与模型白名单逐层校验&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;租户隔离&lt;&#x2F;td&gt;&lt;td&gt;Key、配置与价格按租户隔离；账号管理只作用于自己的子树&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;注册防刷&lt;&#x2F;td&gt;&lt;td&gt;IP 与邮箱频率限制、渐进延迟、自动封禁与全站日配额&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;内存保护&lt;&#x2F;td&gt;&lt;td&gt;进程启动时禁用内存转储&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;bu-shu-qing-dan&quot;&gt;部署清单&lt;&#x2F;h2&gt;
&lt;h3 id=&quot;mi-yao&quot;&gt;密钥&lt;&#x2F;h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
root Key 与数据库密码使用随机生成的值，&lt;code&gt;docker-compose.yml&lt;&#x2F;code&gt; 权限为 &lt;code&gt;600&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
root Key 只用于管理，不用于模型调用，不分发给应用。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
应用使用独立的子账号 Key，按环境与用途拆分。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
怀疑泄露时通过 &lt;code&gt;POST &#x2F;x-self&lt;&#x2F;code&gt; 轮换，旧 Key 立即失效。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h3 id=&quot;wang-luo&quot;&gt;网络&lt;&#x2F;h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
端口保持绑定 &lt;code&gt;127.0.0.1&lt;&#x2F;code&gt;，只允许反向代理访问 API 与控制台端口。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
PostgreSQL 与 Redis 不发布到主机端口（模板默认如此）。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
全部入口启用 HTTPS。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
&lt;code&gt;TRUSTED_PROXY_CIDRS&lt;&#x2F;code&gt; 只包含你自己的代理地址，避免客户端伪造 IP。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
在代理层屏蔽不需要对外暴露的工具路径：&lt;code&gt;&#x2F;x-gkey&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;x-ekey&#x2F;&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;x-dkey&#x2F;&lt;&#x2F;code&gt;。它们无需认证，只用于生成与编解码 Key，对外部用户没有用途。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;nginx&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;location ~&lt;&#x2F;span&gt;&lt;span style=&quot;color: #DBEDFF;&quot;&gt; ^&#x2F;x-(gkey|ekey|dkey) &lt;&#x2F;span&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; return&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; 404&lt;&#x2F;span&gt;&lt;span&gt;; }&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;ul&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
如果不对公众开放，可按来源 IP 限制配置管理控制台的访问。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h3 id=&quot;you-jian&quot;&gt;邮件&lt;&#x2F;h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
在 &lt;code&gt;docker-compose.yml&lt;&#x2F;code&gt; 中为邮件服务配置自己的 SMTP。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
保持模板中 API 容器的 &lt;code&gt;EMAIL_SMTP&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_AUTH&lt;&#x2F;code&gt;、&lt;code&gt;EMAIL_PASS&lt;&#x2F;code&gt; 为空字符串，或显式设置为你自己的值，&lt;strong&gt;不要依赖代码中的默认值&lt;&#x2F;strong&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
把 &lt;code&gt;XAI_MAIL&lt;&#x2F;code&gt; 设为你自己的运营邮箱，接收未知模型、故障切换等通知。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
注意欢迎邮件与 Key 轮换邮件中包含明文 API Key，请确保邮件链路使用 TLS。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h3 id=&quot;shang-you-key&quot;&gt;上游 Key&lt;&#x2F;h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
查询 Key 时使用 &lt;code&gt;fields=summary&lt;&#x2F;code&gt;；&lt;code&gt;full&lt;&#x2F;code&gt; 模式与 &lt;code&gt;GET &#x2F;x-conf&lt;&#x2F;code&gt; 的休眠&#x2F;禁用列表会返回明文。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
为被上游吊销的 Key 配置 &lt;code&gt;AUTO_DISABLE_KEY_STATUS=401&lt;&#x2F;code&gt;，让其自动退出轮询。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
定期轮换上游 Key，并在上游控制台设置用量上限作为最后一道防线。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h3 id=&quot;fang-wen-kong-zhi&quot;&gt;访问控制&lt;&#x2F;h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
需要额度与限速生效的账号使用 Role 2 或 3（Role 0&#x2F;1 不检查额度与限速）。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
生产账号设置 &lt;code&gt;AllowIPs&lt;&#x2F;code&gt;；对外分发的账号设置 &lt;code&gt;AllowModels&lt;&#x2F;code&gt; 与 &lt;code&gt;Resources&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
保持 &lt;code&gt;USER_FILTER=true&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
不开放注册的部署设置 &lt;code&gt;SIGN_ENABLE=false&lt;&#x2F;code&gt;；开放注册时配置 &lt;code&gt;SIGNUP_ALLOW_DOMAINS&lt;&#x2F;code&gt; 或 &lt;code&gt;SIGNUP_DENY_DOMAINS&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h3 id=&quot;ri-zhi-yu-cuo-wu&quot;&gt;日志与错误&lt;&#x2F;h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
生产环境保持 &lt;code&gt;LOG_ENABLE=false&lt;&#x2F;code&gt;，排障时短时开启。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
面向终端用户的服务可设置 &lt;code&gt;MASK_ERRORS=true&lt;&#x2F;code&gt;，隐藏上游错误细节。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
在代理与应用日志中脱敏 &lt;code&gt;Authorization&lt;&#x2F;code&gt;、&lt;code&gt;x-api-key&lt;&#x2F;code&gt; 请求头。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h3 id=&quot;shu-ju&quot;&gt;数据&lt;&#x2F;h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
PostgreSQL 与 Redis 的备份复制到异机，并定期演练恢复。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;input disabled=&quot;&quot; type=&quot;checkbox&quot;&#x2F;&gt;
限制宿主机上 &lt;code&gt;backups&#x2F;&lt;&#x2F;code&gt; 目录的访问权限。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;lou-dong-bao-gao&quot;&gt;漏洞报告&lt;&#x2F;h2&gt;
&lt;p&gt;发现安全问题时，请发送邮件至 &lt;a href=&quot;mailto:ywgx@xabcloud.com&quot;&gt;ywgx@xabcloud.com&lt;&#x2F;a&gt;，不要在公开 Issue 中披露细节。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;architecture&#x2F;#jia-mi-mo-xing&quot;&gt;架构&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;configuration&#x2F;&quot;&gt;配置参考&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>DeepSeek 全家桶接入</title>
        <published>2026-11-14T09:00:00+00:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/guides/deepseek/"/>
        <id>https://xsicontrol.com/docs/guides/deepseek/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/guides/deepseek/">&lt;p&gt;XSI 对 DeepSeek 的接口做透传：请求体原样转发（只按模型映射改写 &lt;code&gt;model&lt;&#x2F;code&gt;），响应原样返回。DeepSeek 官方文档里的参数和返回字段都可以直接使用，包括 &lt;code&gt;safety_check&lt;&#x2F;code&gt;、&lt;code&gt;title&lt;&#x2F;code&gt;、&lt;code&gt;latest_reminder&lt;&#x2F;code&gt;、&lt;code&gt;deepseek_web_search&lt;&#x2F;code&gt;、&lt;code&gt;deepseek_read_url&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;p&gt;所有路径带不带 &lt;code&gt;&#x2F;v1&lt;&#x2F;code&gt; 前缀都可以。鉴权用 &lt;code&gt;Authorization: Bearer $XSI_API_KEY&lt;&#x2F;code&gt; 或 &lt;code&gt;x-api-key: $XSI_API_KEY&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;jie-kou-yi-lan&quot;&gt;接口一览&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;接口&lt;&#x2F;th&gt;&lt;th&gt;路径&lt;&#x2F;th&gt;&lt;th&gt;计费模型&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;Chat Completions&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;chat&#x2F;completions&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-flash&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Responses&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;responses&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;同上&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Messages（Anthropic 格式）&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;messages&lt;&#x2F;code&gt;、&lt;code&gt;POST &#x2F;v1&#x2F;messages&#x2F;count_tokens&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;同上&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;网页搜索&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;tools&#x2F;search&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-search&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;网页抓取&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;tools&#x2F;fetch&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-fetch&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;OCR&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;tools&#x2F;ocr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-ocr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;语音合成&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;tools&#x2F;tts&lt;&#x2F;code&gt;，或 WebSocket 同一路径&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-tts&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;语音识别&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;tools&#x2F;asr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-asr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;文件&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;files&lt;&#x2F;code&gt;、&lt;code&gt;GET &#x2F;v1&#x2F;files&lt;&#x2F;code&gt;、&lt;code&gt;GET &#x2F;v1&#x2F;files&#x2F;{id}&lt;&#x2F;code&gt;、&lt;code&gt;DELETE &#x2F;v1&#x2F;files&#x2F;{id}&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;文档解析为 &lt;code&gt;deepseek-files&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;余额&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;GET &#x2F;user&#x2F;balance&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;不计费&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;dui-hua-yu-lian-wang-gong-ju&quot;&gt;对话与联网工具&lt;&#x2F;h2&gt;
&lt;p&gt;三种协议都支持服务端联网工具。下面是 Chat Completions 的例子：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span&gt; $XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;chat&#x2F;completions&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;model&amp;quot;: &amp;quot;deepseek-flash&amp;quot;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;thinking&amp;quot;: {&amp;quot;type&amp;quot;: &amp;quot;enabled&amp;quot;},&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;tools&amp;quot;: [{&amp;quot;type&amp;quot;: &amp;quot;deepseek_web_search&amp;quot;}, {&amp;quot;type&amp;quot;: &amp;quot;deepseek_read_url&amp;quot;}],&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;messages&amp;quot;: [{&amp;quot;role&amp;quot;: &amp;quot;user&amp;quot;, &amp;quot;content&amp;quot;: &amp;quot;DeepSeek V4.1 有哪些更新？&amp;quot;}],&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;stream&amp;quot;: true&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;  }&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;计费按上游返回的最终用量：输入、缓存命中、输出 Token，加上联网工具次数。工具次数取 &lt;code&gt;usage.server_tool_use&lt;&#x2F;code&gt; 里的 &lt;code&gt;tool_search&lt;&#x2F;code&gt;、&lt;code&gt;tool_fetch&lt;&#x2F;code&gt;、&lt;code&gt;tool_image_search&lt;&#x2F;code&gt; 之和，按模型的 &lt;code&gt;Query&lt;&#x2F;code&gt; 单价计。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;gong-ju-jie-kou-de-ji-fei-dan-wei&quot;&gt;工具接口的计费单位&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;计费模型&lt;&#x2F;th&gt;&lt;th&gt;计费单位&lt;&#x2F;th&gt;&lt;th&gt;默认单价&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;deepseek-search&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每次返回了结果的搜索&lt;&#x2F;td&gt;&lt;td&gt;¥0.005&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;deepseek-fetch&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;每次成功的抓取&lt;&#x2F;td&gt;&lt;td&gt;¥0.005&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;deepseek-ocr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;识别成功的页数&lt;&#x2F;td&gt;&lt;td&gt;¥0.0015 &#x2F; 页&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;deepseek-tts&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;字符数，汉字算 2 个&lt;&#x2F;td&gt;&lt;td&gt;¥3 &#x2F; 万字符&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;deepseek-asr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;音频秒数，不足 1 秒按 1 秒&lt;&#x2F;td&gt;&lt;td&gt;¥0.78 &#x2F; 小时&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;deepseek-files&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;文档解析页数，按文件大小估算&lt;&#x2F;td&gt;&lt;td&gt;¥0.0015 &#x2F; 页&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;没有结果的搜索、失败的请求不计费。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;wen-jian&quot;&gt;文件&lt;&#x2F;h2&gt;
&lt;p&gt;上传、引用、查询、删除的用法与 DeepSeek 官方一致，OpenAI 格式和 Anthropic 格式都支持。Anthropic 格式需要带请求头 &lt;code&gt;anthropic-beta: files-api-2025-04-14&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span&gt; $XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;files&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -F&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; purpose=&amp;quot;text_recognition&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -F&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; file=&amp;quot;@report.pdf&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;需要了解的几点：&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;文件只属于上传它的用户。&lt;&#x2F;strong&gt; 文件列表只显示本人登记的文件；其他用户按 ID 查询、删除或在对话中引用它会得到 400。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;文档解析按大小估算页数计费。&lt;&#x2F;strong&gt; 以 &lt;code&gt;text_recognition&lt;&#x2F;code&gt; 或 &lt;code&gt;rich_layout_recognition&lt;&#x2F;code&gt; 上传时，每 10 KiB 算一页，最少 1 页，最多 1000 页。以 &lt;code&gt;user_data&lt;&#x2F;code&gt; 上传不计费。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;文件列表只包含用同一种格式上传的文件。&lt;&#x2F;strong&gt; 用 OpenAI 格式上传的文件出现在 OpenAI 格式的列表里，Anthropic 格式同理。按 id 查询、删除和引用不受这个限制。&lt;&#x2F;li&gt;
&lt;li&gt;列表不支持 &lt;code&gt;before_id&lt;&#x2F;code&gt; 参数。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;yu-yin-he-cheng-websocket&quot;&gt;语音合成 WebSocket&lt;&#x2F;h2&gt;
&lt;p&gt;连接 &lt;code&gt;wss:&#x2F;&#x2F;&amp;lt;XSI 域名&amp;gt;&#x2F;v1&#x2F;tools&#x2F;tts&lt;&#x2F;code&gt;，消息格式与 DeepSeek 官方一致。鉴权有两种方式：&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;请求头 &lt;code&gt;Authorization: Bearer $XSI_API_KEY&lt;&#x2F;code&gt;；&lt;&#x2F;li&gt;
&lt;li&gt;浏览器里无法设置请求头时，用子协议 &lt;code&gt;Sec-WebSocket-Protocol: tts, bearer.$XSI_API_KEY&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;一次会话按发送的字符数计费。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;yu-e&quot;&gt;余额&lt;&#x2F;h2&gt;
&lt;p&gt;&lt;code&gt;GET &#x2F;user&#x2F;balance&lt;&#x2F;code&gt; 按 DeepSeek 的格式返回你在 XSI 的余额：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;json&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  &amp;quot;is_available&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; true&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  &amp;quot;balance_infos&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: [&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;currency&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;CNY&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;total_balance&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;110.00&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;granted_balance&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;0.00&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;topped_up_balance&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;110.00&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;  ]&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;guan-li-yuan-xu-zhi&quot;&gt;管理员须知&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;添加 Provider 为 &lt;code&gt;https:&#x2F;&#x2F;api.deepseek.com&lt;&#x2F;code&gt; 的 Key 后，&lt;code&gt;deepseek*&lt;&#x2F;code&gt; 会自动映射到这个分组，上表里的计费模型都匹配这条规则。&lt;&#x2F;li&gt;
&lt;li&gt;文件上传（&lt;code&gt;user_data&lt;&#x2F;code&gt;）和文件列表的请求里没有模型信息，使用 &lt;code&gt;files&lt;&#x2F;code&gt; 这个模型名做分组映射。分组里有多家服务商时，请把 &lt;code&gt;files&lt;&#x2F;code&gt; 映射到 DeepSeek 所在的分组。&lt;&#x2F;li&gt;
&lt;li&gt;同一个用户的文件会固定在同一个上游账号上，引用文件的对话请求也会发到这个账号。&lt;&#x2F;li&gt;
&lt;li&gt;文件登记保存在 Redis 里，默认在用户最后一次上传后保留 3 年，可用环境变量 &lt;code&gt;FILE_REGISTRY_TTL&lt;&#x2F;code&gt; 调整。删除用户时先删除登记，再尽力删除上游文件（上游 Key 不可用或删除失败时，上游文件可能残留）。&lt;&#x2F;li&gt;
&lt;li&gt;默认单价是 DeepSeek 的高峰时段刊例价，可以在定价里修改。&lt;&#x2F;li&gt;
&lt;li&gt;工具和文档解析的计费模型只对各自的接口有效：不能用在对话接口上，也不能通过模型映射换成别的模型，否则请求会得到 400。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>Claude Code</title>
        <published>2025-07-20T09:19:42+00:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/tools/claude-code/"/>
        <id>https://xsicontrol.com/docs/tools/claude-code/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/tools/claude-code/">














&lt;figure class=&quot;content-image&quot;&gt;
    &lt;img src=&quot;https:&amp;#x2F;&amp;#x2F;xsicontrol.com&amp;#x2F;processed_images&amp;#x2F;claude-code.c5bbe3dd9acb287e.webp&quot;
         alt=&quot;claude code&quot;
         decoding=&quot;async&quot;
         loading=&quot;lazy&quot;
         width=&quot;1466&quot; height=&quot;860&quot;
         &gt;
    
&lt;&#x2F;figure&gt;
&lt;p&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;www.anthropic.com&#x2F;claude-code&quot;&gt;Claude Code&lt;&#x2F;a&gt; 是 Anthropic 官方的终端编码助手。它支持自定义 API 端点与 Key，因此可以直接通过 XSI 使用 Anthropic Messages 协议。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;an-zhuang&quot;&gt;安装&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;# macOS &#x2F; Linux &#x2F; WSL&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -fsSL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; https:&#x2F;&#x2F;claude.ai&#x2F;install.sh&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; |&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt; bash&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;# macOS（Homebrew）&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;brew&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; install&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; --cask&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; claude-code&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;powershell&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;# Windows PowerShell&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;irm https:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;&#x2F;&#x2F;&lt;&#x2F;span&gt;&lt;span&gt;claude.ai&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;&#x2F;&lt;&#x2F;span&gt;&lt;span&gt;install.ps1 &lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;|&lt;&#x2F;span&gt;&lt;span&gt; iex&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;安装后运行 &lt;code&gt;claude doctor&lt;&#x2F;code&gt; 检查版本与安装状态。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;pei-zhi&quot;&gt;配置&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; ANTHROPIC_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;https:&#x2F;&#x2F;api.xsicontrol.com&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;   # 或你自己的 API 域名，不带 &#x2F;v1&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; ANTHROPIC_AUTH_TOKEN&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;sk-Xvs...&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;claude&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;powershell&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;$&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;env:&lt;&#x2F;span&gt;&lt;span&gt;ANTHROPIC_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;https:&#x2F;&#x2F;api.xsicontrol.com&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;$&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;env:&lt;&#x2F;span&gt;&lt;span&gt;ANTHROPIC_AUTH_TOKEN&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;sk-Xvs...&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;claude&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;也可以写入 &lt;code&gt;~&#x2F;.claude&#x2F;settings.json&lt;&#x2F;code&gt;，对所有终端生效：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;json&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  &amp;quot;env&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: {&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;    &amp;quot;ANTHROPIC_BASE_URL&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;https:&#x2F;&#x2F;api.xsicontrol.com&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;    &amp;quot;ANTHROPIC_AUTH_TOKEN&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;sk-Xvs...&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;  }&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;zhi-ding-mo-xing&quot;&gt;指定模型&lt;&#x2F;h2&gt;
&lt;p&gt;Claude Code 默认使用 Claude 系列模型。如需固定使用某个模型，或让它使用运营方配置的其他 Anthropic 兼容模型：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; ANTHROPIC_DEFAULT_OPUS_MODEL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;claude-opus-5-5&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; ANTHROPIC_DEFAULT_SONNET_MODEL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;claude-sonnet-5-5&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; ANTHROPIC_DEFAULT_HAIKU_MODEL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;claude-haiku-5-5&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;模型名须在价格表中，且账号有权使用。运营方也可以在服务端用 &lt;code&gt;MODEL_MAPPER&lt;&#x2F;code&gt; 统一改写模型名，客户端无需修改。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;yan-zheng&quot;&gt;验证&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;claude&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -p&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;请用一句话回答：连接正常&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;用量可在账户管理控制台或 &lt;code&gt;GET &#x2F;dashboard&#x2F;live&lt;&#x2F;code&gt; 中查看。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;shuo-ming&quot;&gt;说明&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;XSI 对 &lt;code&gt;&#x2F;v1&#x2F;messages&lt;&#x2F;code&gt; 启用粘性会话，同一会话固定到同一个上游 Key，提示缓存命中率更高。&lt;&#x2F;li&gt;
&lt;li&gt;遇到 &lt;code&gt;401&lt;&#x2F;code&gt; 请检查 Key；&lt;code&gt;403&lt;&#x2F;code&gt; 通常是模型或 IP 白名单限制；&lt;code&gt;429&lt;&#x2F;code&gt; 为额度或限速，详见《&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;errors&#x2F;&quot;&gt;错误码&lt;&#x2F;a&gt;》。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;xiang-guan-zi-yuan&quot;&gt;相关资源&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;docs.anthropic.com&#x2F;en&#x2F;docs&#x2F;claude-code&#x2F;overview&quot;&gt;Claude Code 官方文档&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;anthropics&#x2F;claude-code&quot;&gt;Claude Code GitHub 仓库&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;proxy&#x2F;&quot;&gt;Router API：Anthropic 兼容接口&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>Codex CLI &#x2F; App</title>
        <published>2025-07-20T09:19:42+00:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/tools/codex/"/>
        <id>https://xsicontrol.com/docs/tools/codex/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/tools/codex/">














&lt;figure class=&quot;content-image&quot;&gt;
    &lt;img src=&quot;https:&amp;#x2F;&amp;#x2F;xsicontrol.com&amp;#x2F;processed_images&amp;#x2F;codex.c9305fd915501653.webp&quot;
         alt=&quot;codex&quot;
         decoding=&quot;async&quot;
         loading=&quot;lazy&quot;
         width=&quot;2400&quot; height=&quot;1350&quot;
         &gt;
    
&lt;&#x2F;figure&gt;
&lt;p&gt;Codex 通过自定义 Provider 使用 Responses 协议接入 XSI。完成 &lt;code&gt;~&#x2F;.codex&#x2F;config.toml&lt;&#x2F;code&gt; 与环境变量配置后，Codex CLI 与 Codex App 共用同一套连接参数。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;pei-zhi&quot;&gt;配置&lt;&#x2F;h2&gt;
&lt;p&gt;配置文件位置：Linux &#x2F; macOS 为 &lt;code&gt;~&#x2F;.codex&#x2F;config.toml&lt;&#x2F;code&gt;，Windows 为 &lt;code&gt;%USERPROFILE%\.codex\config.toml&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;toml&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;model_provider =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;xsi&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;model =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;gpt-6.2-sol&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;approval_policy =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;on-request&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;sandbox_mode =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;workspace-write&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;[&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;model_providers&lt;&#x2F;span&gt;&lt;span&gt;.&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;xsi&lt;&#x2F;span&gt;&lt;span&gt;]&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;name =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;XSI&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;base_url =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;https:&#x2F;&#x2F;api.xsicontrol.com&#x2F;v1&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;   # 或你自己的 API 域名&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;wire_api =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;responses&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;requires_openai_auth =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; false&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;env_key =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;XSI_API_KEY&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;supports_websockets =&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; false&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;设置 Key 并启动：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;sk-Xvs...&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;codex&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;powershell&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;$&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;env:&lt;&#x2F;span&gt;&lt;span&gt;XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;sk-Xvs...&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;codex&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;验证：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;codex&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; exec &amp;quot;请用一句话回答：连接正常&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;&lt;code&gt;model&lt;&#x2F;code&gt; 可以是价格表中任意支持 Responses 协议的模型；账户管理控制台的“配置说明”页提供一键配置脚本，会自动填入当前账号的 Key。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;responses-websocket&quot;&gt;Responses WebSocket&lt;&#x2F;h2&gt;
&lt;p&gt;把 &lt;code&gt;supports_websockets&lt;&#x2F;code&gt; 改为 &lt;code&gt;true&lt;&#x2F;code&gt; 即使用 Responses WebSocket 模式：同一连接内只发送新增输入，长会话的延迟与流量更低。部署方需确保反向代理支持 WebSocket，见《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;p&gt;&lt;strong&gt;中途打断时的计费&lt;&#x2F;strong&gt;：&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;HTTP 模式&lt;&#x2F;strong&gt;：Codex 断开连接并携带完整历史重发。被打断的那次请求如果没有拿到上游用量，XSI 参考同一会话最近一次的真实用量估算缺失部分，会话中已缓存的部分按缓存价计费。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;WebSocket 模式&lt;&#x2F;strong&gt;：输入新内容打断时，Codex 会等待上游返回真实用量；按 Esc 时，XSI 请求上游中断，上游支持中断的模型按返回的真实用量计费，否则同样按会话用量估算。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;长会话、频繁打断的场景建议开启 WebSocket；网络或代理不支持 WebSocket 时保持 HTTP。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;hui-hua-nian-xing&quot;&gt;会话粘性&lt;&#x2F;h2&gt;
&lt;p&gt;Codex 会携带会话标识，XSI 据此把同一会话固定到同一个上游 Key，以提高提示缓存命中率并降低成本，无需额外配置。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;xiang-guan-zi-yuan&quot;&gt;相关资源&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;openai.com&#x2F;codex&#x2F;&quot;&gt;OpenAI Codex&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;openai&#x2F;codex&quot;&gt;Codex CLI 源码&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;proxy&#x2F;&quot;&gt;Router API&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;realtime&#x2F;&quot;&gt;WebSocket 与实时接口&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>Router API</title>
        <published>2025-03-01T08:00:00+00:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/api-reference/proxy/"/>
        <id>https://xsicontrol.com/docs/api-reference/proxy/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/api-reference/proxy/">&lt;h1 id=&quot;router-api&quot;&gt;Router API&lt;&#x2F;h1&gt;
&lt;p&gt;XSI 是&lt;strong&gt;协议原生&lt;&#x2F;strong&gt;的路由器：它不把请求翻译成某种“统一格式”，而是保持每个上游协议的请求与响应语义，只在必要处改写模型名、路径与上游凭证。因此官方 SDK、Codex、Claude Code 等客户端只需替换 &lt;code&gt;base_url&lt;&#x2F;code&gt; 与 API Key。&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;https:&#x2F;&#x2F;api.xsicontrol.com&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;   # 或你自己的 API 域名&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;sk-Xvs...&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;qing-qiu-ru-he-bei-chu-li&quot;&gt;请求如何被处理&lt;&#x2F;h2&gt;
&lt;p&gt;每个模型请求依次经过以下步骤：&lt;&#x2F;p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;认证&lt;&#x2F;strong&gt;：解析调用方 Key，检查账号状态与认证失败频率。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;账号准入&lt;&#x2F;strong&gt;：IP 白名单 → 账号状态、冻结、日&#x2F;月额度、余额、账号级 RPM&#x2F;TPM → 资源（路径）白名单。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;模型解析&lt;&#x2F;strong&gt;：从请求体（或 URL）读取模型名，按 &lt;code&gt;MODEL_MAPPER&lt;&#x2F;code&gt; 等规则映射为上游模型。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;模型准入&lt;&#x2F;strong&gt;：模型白名单（&lt;code&gt;AllowModels&lt;&#x2F;code&gt;）与模型级限额（&lt;code&gt;MODEL_LIMITS&lt;&#x2F;code&gt;）。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;选择上游&lt;&#x2F;strong&gt;：按模型确定 Level（分组），在该组的 Key 池中按粘性会话或轮询选择一个 Key。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;转发&lt;&#x2F;strong&gt;：改写路径与上游鉴权头后转发；上游返回可重试错误时，在向客户端写出任何字节之前自动换 Key 重试。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;计量与结算&lt;&#x2F;strong&gt;：从响应（含 SSE 流）中旁路读取用量，按价格表结算。&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;p&gt;路由细节见《&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;routing&#x2F;&quot;&gt;路由与故障转移&lt;&#x2F;a&gt;》，计费细节见《&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;billing&#x2F;&quot;&gt;计费与价格&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;openai-jian-rong-jie-kou&quot;&gt;OpenAI 兼容接口&lt;&#x2F;h2&gt;
&lt;p&gt;除下文标注“本地处理”的路径外，XSI 会把&lt;strong&gt;任何路径与方法&lt;&#x2F;strong&gt;转发给选中 Key 的上游，因此上游支持的接口（如 &lt;code&gt;&#x2F;v1&#x2F;batches&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;fine_tuning&#x2F;*&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;vector_stores&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;completions&lt;&#x2F;code&gt;）都可以直接使用。下表列出 XSI 有专门处理的接口：&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;能力&lt;&#x2F;th&gt;&lt;th&gt;方法与路径&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;Chat Completions&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;chat&#x2F;completions&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;支持粘性会话&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Responses&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;responses&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;支持粘性会话；也可通过 WebSocket 连接，见《&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;realtime&#x2F;&quot;&gt;WebSocket 与实时接口&lt;&#x2F;a&gt;》&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Responses 压缩&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;responses&#x2F;compact&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;XSI 强制 &lt;code&gt;Accept: application&#x2F;json&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Responses 子资源&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;GET &#x2F;v1&#x2F;responses&#x2F;{id}&lt;&#x2F;code&gt;、&lt;code&gt;POST &#x2F;v1&#x2F;responses&#x2F;{id}&#x2F;cancel&lt;&#x2F;code&gt;、&lt;code&gt;GET &#x2F;v1&#x2F;responses&#x2F;{id}&#x2F;input_items&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;与创建请求走同一粘性路径；GET 不计费&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Embeddings&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;embeddings&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;按 &lt;code&gt;usage.prompt_tokens&lt;&#x2F;code&gt; 计费&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;图片生成与编辑&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;images&#x2F;generations&lt;&#x2F;code&gt;、&lt;code&gt;POST &#x2F;v1&#x2F;images&#x2F;edits&lt;&#x2F;code&gt;、&lt;code&gt;POST &#x2F;v1&#x2F;images&#x2F;variations&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;按张或按 Token 计费，见下文&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;视频生成&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;videos&#x2F;generations&lt;&#x2F;code&gt;、&lt;code&gt;GET &#x2F;v1&#x2F;videos&#x2F;{request_id}&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;异步任务，见下文&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;音频&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;audio&#x2F;transcriptions&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;audio&#x2F;translations&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;audio&#x2F;speech&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;转录与翻译未指定模型时按 &lt;code&gt;whisper-1&lt;&#x2F;code&gt; 路由&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Moderations&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;moderations&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;未指定模型时按 &lt;code&gt;omni-moderation-latest&lt;&#x2F;code&gt; 路由&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Files&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;&#x2F;v1&#x2F;files&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;files&#x2F;{id}&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;列表请求无模型，使用伪模型名 &lt;code&gt;files&lt;&#x2F;code&gt; 做分组映射&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Threads&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;&#x2F;v1&#x2F;threads&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;threads&#x2F;{id}&#x2F;...&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;集合路径使用伪模型名 &lt;code&gt;thread&lt;&#x2F;code&gt;，子路径以线程 ID 作为路径模型值&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Realtime&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;GET &#x2F;v1&#x2F;realtime&lt;&#x2F;code&gt;（WebSocket）、&lt;code&gt;POST &#x2F;v1&#x2F;realtime&#x2F;calls&lt;&#x2F;code&gt;、&lt;code&gt;POST &#x2F;v1&#x2F;realtime&#x2F;client_secrets&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;见《&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;realtime&#x2F;&quot;&gt;WebSocket 与实时接口&lt;&#x2F;a&gt;》&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Live&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;live&#x2F;sessions&lt;&#x2F;code&gt;、WebSocket &lt;code&gt;&#x2F;v1&#x2F;live&#x2F;sessions&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;见《&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;realtime&#x2F;&quot;&gt;WebSocket 与实时接口&lt;&#x2F;a&gt;》&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;模型列表&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;GET &#x2F;v1&#x2F;models&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;strong&gt;本地处理&lt;&#x2F;strong&gt;，见&lt;a href=&quot;https:&#x2F;&#x2F;xsicontrol.com&#x2F;docs&#x2F;api-reference&#x2F;proxy&#x2F;#cha-xun-jie-kou&quot;&gt;查询接口&lt;&#x2F;a&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h3 id=&quot;guan-yu-v1-qian-zhui&quot;&gt;关于 &lt;code&gt;&#x2F;v1&lt;&#x2F;code&gt; 前缀&lt;&#x2F;h3&gt;
&lt;ul&gt;
&lt;li&gt;本地处理的路由（模型列表、余额、Realtime、Live、视频、DeepSeek 工具与文件）同时接受带与不带 &lt;code&gt;&#x2F;v1&lt;&#x2F;code&gt; 的写法。&lt;&#x2F;li&gt;
&lt;li&gt;转发路由能否省略 &lt;code&gt;&#x2F;v1&lt;&#x2F;code&gt; 取决于上游的路径映射。对 &lt;code&gt;api.openai.com&lt;&#x2F;code&gt;，XSI 会把 &lt;code&gt;&#x2F;chat&#x2F;completions&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;responses&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;embeddings&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;models&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;images&#x2F;*&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;audio&#x2F;*&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;files&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;batches&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;fine_tuning&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;realtime&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;moderations&lt;&#x2F;code&gt; 补全为 &lt;code&gt;&#x2F;v1&#x2F;...&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;新接入请始终使用 &lt;code&gt;&#x2F;v1&#x2F;...&lt;&#x2F;code&gt;&lt;&#x2F;strong&gt;。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h3 id=&quot;shi-li-chat-completions&quot;&gt;示例：Chat Completions&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;chat&#x2F;completions&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;model&amp;quot;: &amp;quot;gpt-6.2-sol&amp;quot;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;messages&amp;quot;: [{&amp;quot;role&amp;quot;: &amp;quot;user&amp;quot;, &amp;quot;content&amp;quot;: &amp;quot;用一句话介绍 XSI&amp;quot;}],&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;stream&amp;quot;: true,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;stream_options&amp;quot;: {&amp;quot;include_usage&amp;quot;: true}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;  }&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;Chat Completions 流式请求建议设置 &lt;code&gt;stream_options.include_usage&lt;&#x2F;code&gt;。上游流中没有 usage 时，XSI 会按实际输出与会话内容估算用量。&lt;&#x2F;p&gt;
&lt;h3 id=&quot;shi-li-responses&quot;&gt;示例：Responses&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;responses&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;model&amp;quot;: &amp;quot;gpt-6.2-sol&amp;quot;, &amp;quot;input&amp;quot;: &amp;quot;只回复 OK&amp;quot;}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;python&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;from&lt;&#x2F;span&gt;&lt;span&gt; openai&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; import&lt;&#x2F;span&gt;&lt;span&gt; OpenAI&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;client&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; =&lt;&#x2F;span&gt;&lt;span&gt; OpenAI(&lt;&#x2F;span&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt;base_url&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;https:&#x2F;&#x2F;api.xsicontrol.com&#x2F;v1&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt; api_key&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;sk-Xvs...&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;)&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;resp&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; =&lt;&#x2F;span&gt;&lt;span&gt; client.responses.create(&lt;&#x2F;span&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt;model&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;gpt-6.2-sol&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt; input&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;只回复 OK&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;)&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;print&lt;&#x2F;span&gt;&lt;span&gt;(resp.output_text)&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h3 id=&quot;tu-pian&quot;&gt;图片&lt;&#x2F;h3&gt;
&lt;ul&gt;
&lt;li&gt;定价表中同时以 Token 计价的图片模型（如 &lt;code&gt;gpt-image-2&lt;&#x2F;code&gt;、&lt;code&gt;gpt-image-2.6-*&lt;&#x2F;code&gt;）按 Token 计费。&lt;&#x2F;li&gt;
&lt;li&gt;其他图片模型按 &lt;code&gt;ImgPricing&lt;&#x2F;code&gt; 计费：&lt;code&gt;尺寸单价 × n + 输入图单价 × 输入图数&lt;&#x2F;code&gt;。默认尺寸为 &lt;code&gt;1024x1024&lt;&#x2F;code&gt;；&lt;code&gt;grok-imagine*&lt;&#x2F;code&gt; 系列按 &lt;code&gt;resolution&lt;&#x2F;code&gt;（如 &lt;code&gt;1k&lt;&#x2F;code&gt;、&lt;code&gt;2k&lt;&#x2F;code&gt;）计价。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;images&#x2F;generations&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;model&amp;quot;: &amp;quot;gpt-image-2.6-flare&amp;quot;, &amp;quot;prompt&amp;quot;: &amp;quot;a lighthouse at dawn&amp;quot;, &amp;quot;size&amp;quot;: &amp;quot;1024x1024&amp;quot;}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h3 id=&quot;shi-pin&quot;&gt;视频&lt;&#x2F;h3&gt;
&lt;p&gt;视频生成是异步流程：&lt;&#x2F;p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code&gt;POST &#x2F;v1&#x2F;videos&#x2F;generations&lt;&#x2F;code&gt; 创建任务。XSI 会把响应中的上游 &lt;code&gt;request_id&lt;&#x2F;code&gt; 替换为一个签名令牌（形如 &lt;code&gt;vjob_...&lt;&#x2F;code&gt;），令牌绑定创建它的 XSI 账号与上游 Key。&lt;&#x2F;li&gt;
&lt;li&gt;使用&lt;strong&gt;同一个 XSI 账号&lt;&#x2F;strong&gt;的 Key 原样轮询 &lt;code&gt;GET &#x2F;v1&#x2F;videos&#x2F;{request_id}&lt;&#x2F;code&gt;。令牌不属于当前账号或已被篡改时返回 &lt;code&gt;400 invalid video request_id&lt;&#x2F;code&gt;；创建任务的上游 Key 已不可用时返回 &lt;code&gt;503 video generation account unavailable&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;ul&gt;
&lt;li&gt;视频创建请求&lt;strong&gt;不会自动重试&lt;&#x2F;strong&gt;，以免重复生成；任何 2xx 响应都视为创建成功并计费。&lt;&#x2F;li&gt;
&lt;li&gt;计费：&lt;code&gt;duration&lt;&#x2F;code&gt;（1–15 秒，默认 6）× 分辨率单价（默认 &lt;code&gt;480p&lt;&#x2F;code&gt;）+ 输入图片数（&lt;code&gt;image&lt;&#x2F;code&gt;、&lt;code&gt;reference_images&lt;&#x2F;code&gt;）× 输入图单价。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;videos&#x2F;generations&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;model&amp;quot;: &amp;quot;grok-imagine-video&amp;quot;, &amp;quot;prompt&amp;quot;: &amp;quot;waves on a quiet beach&amp;quot;, &amp;quot;duration&amp;quot;: 6, &amp;quot;resolution&amp;quot;: &amp;quot;720p&amp;quot;}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;anthropic-jian-rong-jie-kou&quot;&gt;Anthropic 兼容接口&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;能力&lt;&#x2F;th&gt;&lt;th&gt;方法与路径&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;Messages&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;messages&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Token 计数&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;messages&#x2F;count_tokens&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Files&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;&#x2F;v1&#x2F;files&lt;&#x2F;code&gt;（带 &lt;code&gt;anthropic-beta: files-api-...&lt;&#x2F;code&gt; 请求头）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;ul&gt;
&lt;li&gt;鉴权可使用 &lt;code&gt;x-api-key&lt;&#x2F;code&gt; 或 &lt;code&gt;Authorization&lt;&#x2F;code&gt;；XSI 转发给 Anthropic 时只保留一个 &lt;code&gt;x-api-key&lt;&#x2F;code&gt;（上游 Key）。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;code&gt;&#x2F;v1&#x2F;messages&lt;&#x2F;code&gt; 支持粘性会话，有利于提示缓存命中。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;code&gt;count_tokens&lt;&#x2F;code&gt; 的响应不含 usage，不产生 Token 费用。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;messages&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;x-api-key: &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;anthropic-version: 2023-06-01&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;model&amp;quot;: &amp;quot;claude-sonnet-5-5&amp;quot;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;max_tokens&amp;quot;: 1024,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;    &amp;quot;messages&amp;quot;: [{&amp;quot;role&amp;quot;: &amp;quot;user&amp;quot;, &amp;quot;content&amp;quot;: &amp;quot;你好&amp;quot;}]&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;  }&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;python&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;import&lt;&#x2F;span&gt;&lt;span&gt; anthropic&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;client&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; =&lt;&#x2F;span&gt;&lt;span&gt; anthropic.Anthropic(&lt;&#x2F;span&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt;base_url&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;https:&#x2F;&#x2F;api.xsicontrol.com&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt; api_key&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;sk-Xvs...&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;)&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;msg&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; =&lt;&#x2F;span&gt;&lt;span&gt; client.messages.create(&lt;&#x2F;span&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt;model&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;claude-sonnet-5-5&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt; max_tokens&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;1024&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #FFAB70;&quot;&gt;                             messages&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span&gt;[{&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;role&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;user&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;content&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;你好&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;}])&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;print&lt;&#x2F;span&gt;&lt;span&gt;(msg.content[&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;0&lt;&#x2F;span&gt;&lt;span&gt;].text)&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;gemini-yuan-sheng-jie-kou&quot;&gt;Gemini 原生接口&lt;&#x2F;h2&gt;
&lt;p&gt;模型写在 URL 中的路径都按 Gemini 原生协议处理：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;&#x2F;v1beta&#x2F;models&#x2F;{model}:generateContent&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;&#x2F;v1beta&#x2F;models&#x2F;{model}:streamGenerateContent?alt=sse&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;&#x2F;v1beta&#x2F;models&#x2F;{model}:countTokens&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;&#x2F;v1beta&#x2F;models&#x2F;{model}:embedContent&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;同样支持 &lt;code&gt;&#x2F;v1beta1&#x2F;models&#x2F;&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1alpha&#x2F;models&#x2F;&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;models&#x2F;{model}:...&lt;&#x2F;code&gt; 前缀，以及包含 &lt;code&gt;&#x2F;publishers&#x2F;google&#x2F;models&#x2F;{model}&lt;&#x2F;code&gt; 的 Vertex 风格路径。&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;以 URL 中的模型为准&lt;&#x2F;strong&gt;，请求体中的 &lt;code&gt;model&lt;&#x2F;code&gt; 被忽略；模型映射会直接改写 URL。&lt;&#x2F;li&gt;
&lt;li&gt;鉴权使用 &lt;code&gt;x-goog-api-key&lt;&#x2F;code&gt; 或 &lt;code&gt;Authorization&lt;&#x2F;code&gt;，不支持 &lt;code&gt;?key=&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;路径含 &lt;code&gt;streamGenerateContent&lt;&#x2F;code&gt;、带 &lt;code&gt;?alt=sse&lt;&#x2F;code&gt; 或 &lt;code&gt;Accept: text&#x2F;event-stream&lt;&#x2F;code&gt; 时按流式处理。&lt;&#x2F;li&gt;
&lt;li&gt;用量从 &lt;code&gt;usageMetadata&lt;&#x2F;code&gt; 读取。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1beta&#x2F;models&#x2F;&lt;&#x2F;span&gt;&lt;span&gt;$GEMINI_MODEL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;:generateContent&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;x-goog-api-key: &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;contents&amp;quot;: [{&amp;quot;parts&amp;quot;: [{&amp;quot;text&amp;quot;: &amp;quot;你好&amp;quot;}]}]}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;&lt;code&gt;$GEMINI_MODEL&lt;&#x2F;code&gt; 应为运营方已在定价表中配置、且你的账号有权使用的 Gemini 模型。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;deepseek-jie-kou&quot;&gt;DeepSeek 接口&lt;&#x2F;h2&gt;
&lt;p&gt;使用 DeepSeek 上游时，XSI 透传 DeepSeek 的全部接口，包括 Anthropic 格式（&lt;code&gt;&#x2F;anthropic&#x2F;v1&#x2F;messages&lt;&#x2F;code&gt;）、联网搜索与抓取、OCR、语音合成与识别、文件以及余额查询。所有路径带不带 &lt;code&gt;&#x2F;v1&lt;&#x2F;code&gt; 均可。&lt;&#x2F;p&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;接口&lt;&#x2F;th&gt;&lt;th&gt;路径&lt;&#x2F;th&gt;&lt;th&gt;计费模型&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;对话&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;chat&#x2F;completions&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;responses&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;messages&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-flash&lt;&#x2F;code&gt; 等&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;网页搜索 &#x2F; 抓取&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;tools&#x2F;search&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;v1&#x2F;tools&#x2F;fetch&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-search&lt;&#x2F;code&gt;、&lt;code&gt;deepseek-fetch&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;OCR&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;tools&#x2F;ocr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-ocr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;语音合成 &#x2F; 识别&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST &#x2F;v1&#x2F;tools&#x2F;tts&lt;&#x2F;code&gt;（亦可 WebSocket）、&lt;code&gt;POST &#x2F;v1&#x2F;tools&#x2F;asr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;deepseek-tts&lt;&#x2F;code&gt;、&lt;code&gt;deepseek-asr&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;文件&lt;&#x2F;td&gt;&lt;td&gt;&lt;code&gt;POST&#x2F;GET &#x2F;v1&#x2F;files&lt;&#x2F;code&gt;、&lt;code&gt;GET&#x2F;DELETE &#x2F;v1&#x2F;files&#x2F;{id}&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;文档解析为 &lt;code&gt;deepseek-files&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;文件按用户隔离、工具接口的计费单位等细节见《&lt;a href=&quot;&#x2F;docs&#x2F;guides&#x2F;deepseek&#x2F;&quot;&gt;DeepSeek 全家桶接入&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;xai-grok-jie-kou&quot;&gt;xAI（Grok）接口&lt;&#x2F;h2&gt;
&lt;p&gt;&lt;code&gt;api.x.ai&lt;&#x2F;code&gt; 上游按 OpenAI 兼容协议转发（Bearer 鉴权，不做路径映射）。Responses 输出中的 &lt;code&gt;x_search_call&lt;&#x2F;code&gt; 按搜索次数（&lt;code&gt;Query&lt;&#x2F;code&gt; 单价）计费；图片与视频规则见上文。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;liu-shi-xiang-ying&quot;&gt;流式响应&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;以下任一条件成立即按流式处理：JSON 中 &lt;code&gt;&quot;stream&quot;: true&lt;&#x2F;code&gt;、&lt;code&gt;Accept: text&#x2F;event-stream&lt;&#x2F;code&gt;、路径含 &lt;code&gt;streamGenerateContent&lt;&#x2F;code&gt;、查询参数 &lt;code&gt;stream=true&lt;&#x2F;code&gt; 或 &lt;code&gt;alt=sse&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;SSE 原样透传，XSI 仅在旁路解析用量；流式请求会以 &lt;code&gt;Accept-Encoding: identity&lt;&#x2F;code&gt; 发往上游，避免压缩缓冲。&lt;&#x2F;li&gt;
&lt;li&gt;客户端中途断开时，已生成部分仍按实际用量结算。&lt;&#x2F;li&gt;
&lt;li&gt;上游响应头等待上限由 &lt;code&gt;RESPONSE_HEADER_TIMEOUT_SECS&lt;&#x2F;code&gt; 控制，默认 1800 秒。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;nian-xing-hui-hua&quot;&gt;粘性会话&lt;&#x2F;h2&gt;
&lt;p&gt;对 &lt;code&gt;&#x2F;v1&#x2F;responses&lt;&#x2F;code&gt;（含子资源）、&lt;code&gt;*&#x2F;chat&#x2F;completions&lt;&#x2F;code&gt;、&lt;code&gt;*&#x2F;messages&lt;&#x2F;code&gt;，XSI 会把同一会话固定到同一个上游 Key，以提高提示缓存命中率。读取 &lt;code&gt;&#x2F;v1&#x2F;responses&#x2F;{id}&lt;&#x2F;code&gt; 时，请携带与创建时相同的会话请求头并路由到同一 Level，才能回到创建它的上游账号（绑定按会话而非 response ID 保存）。会话标识按以下优先级读取：&lt;&#x2F;p&gt;
&lt;ol&gt;
&lt;li&gt;请求头 &lt;code&gt;session_id&lt;&#x2F;code&gt;&lt;&#x2F;li&gt;
&lt;li&gt;请求头 &lt;code&gt;conversation_id&lt;&#x2F;code&gt;&lt;&#x2F;li&gt;
&lt;li&gt;JSON 请求体的 &lt;code&gt;prompt_cache_key&lt;&#x2F;code&gt;&lt;&#x2F;li&gt;
&lt;li&gt;请求头 &lt;code&gt;session-id&lt;&#x2F;code&gt;&lt;&#x2F;li&gt;
&lt;li&gt;请求头 &lt;code&gt;thread-id&lt;&#x2F;code&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;p&gt;未提供任何标识时，同一账号在同一 Level 上默认固定到同一个 Key。是否启用由运营方配置（&lt;code&gt;STICKY_SCHEDULER&lt;&#x2F;code&gt;、&lt;code&gt;STICKY_LEVELS&lt;&#x2F;code&gt;）。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;zi-dong-zhong-shi-yu-gu-zhang-zhuan-yi&quot;&gt;自动重试与故障转移&lt;&#x2F;h2&gt;
&lt;p&gt;XSI 在服务端完成重试；所有重试都失败时，客户端收到的是&lt;strong&gt;首次失败&lt;&#x2F;strong&gt;的上游响应（状态码与正文原样透传）：&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;重试条件&lt;&#x2F;strong&gt;：仅 POST 请求；上游状态码满足 &lt;code&gt;400 &amp;lt; status &amp;lt; 600&lt;&#x2F;code&gt; 且不在 &lt;code&gt;NO_RETRY_STATUS&lt;&#x2F;code&gt; 中。默认不重试 &lt;code&gt;400、403、404、405、413、421、422、499、500&lt;&#x2F;code&gt;，因此 &lt;code&gt;401、402、408、409、429&lt;&#x2F;code&gt;、&lt;code&gt;502–504&lt;&#x2F;code&gt;、&lt;code&gt;524&lt;&#x2F;code&gt; 等会自动换 Key 重试。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;次数&lt;&#x2F;strong&gt;：当前 Level 内最多 7 次；之后可在账号允许的其他 Level 上每组最多再试 3 次（视账号的路由模式而定）。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;不重试&lt;&#x2F;strong&gt;：视频创建；DeepSeek 文件读取与删除等绑定上游账号的请求不会切换到其他 Key。&lt;&#x2F;li&gt;
&lt;li&gt;Responses 创建返回 &lt;code&gt;400&lt;&#x2F;code&gt; 且错误含 &lt;code&gt;not supported&lt;&#x2F;code&gt; 时（例如某个上游账号不支持该能力），XSI 只在同组内换 Key 重试，每个 Key 最多一次。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;客户端的重试建议：&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;仅对 &lt;code&gt;429&lt;&#x2F;code&gt;、&lt;code&gt;502&lt;&#x2F;code&gt;、&lt;code&gt;503&lt;&#x2F;code&gt; 与网络错误做有限次重试，使用指数退避加随机抖动。&lt;&#x2F;li&gt;
&lt;li&gt;不要自动重复提交图片、视频等非幂等生成请求。&lt;&#x2F;li&gt;
&lt;li&gt;记录状态码与响应正文，但不要记录完整的 API Key。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;kuai-su-dang-wei-yu-fu-wu-deng-ji&quot;&gt;快速档位与服务等级&lt;&#x2F;h2&gt;
&lt;p&gt;请求中的 &lt;code&gt;speed&lt;&#x2F;code&gt;（&lt;code&gt;standard&lt;&#x2F;code&gt;&#x2F;&lt;code&gt;fast&lt;&#x2F;code&gt;&#x2F;&lt;code&gt;ultrafast&lt;&#x2F;code&gt;）或 &lt;code&gt;service_tier&lt;&#x2F;code&gt;（&lt;code&gt;priority&lt;&#x2F;code&gt;&#x2F;&lt;code&gt;fast&lt;&#x2F;code&gt; 视为 fast，&lt;code&gt;ultrafast&lt;&#x2F;code&gt; 视为 ultrafast，&lt;code&gt;default&lt;&#x2F;code&gt;&#x2F;&lt;code&gt;standard&lt;&#x2F;code&gt;&#x2F;&lt;code&gt;flex&lt;&#x2F;code&gt; 视为标准）会影响 Token 单价：&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;以上游响应中的 &lt;code&gt;speed&lt;&#x2F;code&gt;（Anthropic 为 &lt;code&gt;usage.speed&lt;&#x2F;code&gt;）或 &lt;code&gt;service_tier&lt;&#x2F;code&gt; 为准；响应未给出时按请求值计费。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;fast&lt;&#x2F;strong&gt;：Token 费 × 模型的 &lt;code&gt;FastTokenMultiplier&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;ultrafast&lt;&#x2F;strong&gt;：Token 费 × 6。&lt;&#x2F;li&gt;
&lt;li&gt;倍率只作用于 Token 费用，不作用于按次或按单位计价的部分；&lt;code&gt;flex&lt;&#x2F;code&gt; 按标准价计费。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;&lt;a id=&quot;cha-xun-jie-kou&quot;&gt;&lt;&#x2F;a&gt;&lt;&#x2F;p&gt;
&lt;h2 id=&quot;cha-xun-jie-kou&quot;&gt;查询接口&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;方法与路径&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;th&gt;认证&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;GET &#x2F;v1&#x2F;models&lt;&#x2F;code&gt;（亦可 &lt;code&gt;&#x2F;models&lt;&#x2F;code&gt;、&lt;code&gt;&#x2F;dashboard&#x2F;models&lt;&#x2F;code&gt;）&lt;&#x2F;td&gt;&lt;td&gt;模型目录&lt;&#x2F;td&gt;&lt;td&gt;API Key&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;GET &#x2F;user&#x2F;balance&lt;&#x2F;code&gt;（亦可 &lt;code&gt;&#x2F;v1&#x2F;user&#x2F;balance&lt;&#x2F;code&gt;）&lt;&#x2F;td&gt;&lt;td&gt;以 DeepSeek 格式返回当前账号余额&lt;&#x2F;td&gt;&lt;td&gt;API Key&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;GET &#x2F;x-pricing&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;价格目录，见《&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;pricing-api&#x2F;&quot;&gt;价格目录 API&lt;&#x2F;a&gt;》&lt;&#x2F;td&gt;&lt;td&gt;可选&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;GET &#x2F;dashboard&#x2F;*&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;账号状态与用量，见《&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;usage&#x2F;&quot;&gt;账号与用量 API&lt;&#x2F;a&gt;》&lt;&#x2F;td&gt;&lt;td&gt;API Key&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h3 id=&quot;get-v1-models&quot;&gt;&lt;code&gt;GET &#x2F;v1&#x2F;models&lt;&#x2F;code&gt;&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;json&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;object&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;list&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;data&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: [{&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;id&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;gpt-6.2-sol&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;object&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;model&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;owned_by&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;xai&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;}]}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;返回运营方价格表中的全部模型（对话、图片、视频、音频、Rerank 等），按名称排序。列表&lt;strong&gt;不按账号的模型白名单过滤&lt;&#x2F;strong&gt;；账号能否调用某个模型以实际请求的准入结果为准。&lt;&#x2F;p&gt;
&lt;h3 id=&quot;get-user-balance&quot;&gt;&lt;code&gt;GET &#x2F;user&#x2F;balance&lt;&#x2F;code&gt;&lt;&#x2F;h3&gt;
&lt;p&gt;适用于任何上游，不限于 DeepSeek：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;json&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;{&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  &amp;quot;is_available&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; true&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  &amp;quot;balance_infos&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;: [&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;    {&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;&amp;quot;currency&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;CNY&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;total_balance&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;110.00&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;granted_balance&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;0.00&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;,&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; &amp;quot;topped_up_balance&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;:&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;110.00&amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;  ]&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;}&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;&lt;code&gt;is_available&lt;&#x2F;code&gt; 为 &lt;code&gt;true&lt;&#x2F;code&gt; 表示余额大于 0 且账号未被冻结。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;mo-xing-ming-jie-xi&quot;&gt;模型名解析&lt;&#x2F;h2&gt;
&lt;p&gt;请求中的模型名按以下顺序解析，取第一个命中项：&lt;&#x2F;p&gt;
&lt;ol&gt;
&lt;li&gt;运营方临时故障替换（&lt;code&gt;MODEL_FAILOVER&lt;&#x2F;code&gt;）&lt;&#x2F;li&gt;
&lt;li&gt;账号级 &lt;code&gt;ModelMapper&lt;&#x2F;code&gt;（精确，再通配）&lt;&#x2F;li&gt;
&lt;li&gt;租户级 &lt;code&gt;MODEL_MAPPER&lt;&#x2F;code&gt;（精确，再通配）&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;模糊匹配&lt;&#x2F;strong&gt;：模型已在价格表中则原样使用；否则在同家族、同模态中选择版本最接近的已定价模型&lt;&#x2F;li&gt;
&lt;li&gt;原样使用&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;div class=&quot;infobox&quot;&gt;
因为存在模糊匹配，拼错或已下线的模型名可能被映射到同家族的另一个已定价模型。请以价格目录或 &lt;code&gt;&#x2F;v1&#x2F;models&lt;&#x2F;code&gt; 中的名称为准。
&lt;&#x2F;div&gt;
&lt;h2 id=&quot;xian-zhi&quot;&gt;限制&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;项目&lt;&#x2F;th&gt;&lt;th&gt;默认值&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;请求体（解压后）&lt;&#x2F;td&gt;&lt;td&gt;200 MiB（&lt;code&gt;REQUEST_BODY_LIMIT_BYTES&lt;&#x2F;code&gt;）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;Realtime calls &#x2F; Live HTTP 请求体&lt;&#x2F;td&gt;&lt;td&gt;4 MiB&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;WebSocket 单帧&lt;&#x2F;td&gt;&lt;td&gt;16 MiB&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;WebSocket 单连接时长&lt;&#x2F;td&gt;&lt;td&gt;60 分钟（&lt;code&gt;WS_MAX_CONN_DURATION&lt;&#x2F;code&gt;）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;上游响应头等待&lt;&#x2F;td&gt;&lt;td&gt;1800 秒（&lt;code&gt;RESPONSE_HEADER_TIMEOUT_SECS&lt;&#x2F;code&gt;）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;xiang-guan-wen-dang&quot;&gt;相关文档&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;realtime&#x2F;&quot;&gt;WebSocket 与实时接口&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;errors&#x2F;&quot;&gt;错误码&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;routing&#x2F;&quot;&gt;路由与故障转移&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;billing&#x2F;&quot;&gt;计费与价格&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;getting-started&#x2F;sdk-integration&#x2F;&quot;&gt;SDK 集成&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>产品介绍</title>
        <published>2025-03-01T08:00:00+00:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/getting-started/introduction/"/>
        <id>https://xsicontrol.com/docs/getting-started/introduction/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/getting-started/introduction/">&lt;div class=&quot;infobox&quot;&gt;
本站 &lt;b&gt;xsicontrol.com&lt;&#x2F;b&gt; 是 XSI 的多租户云服务 &lt;b&gt;XSI Control&lt;&#x2F;b&gt;：开通租户、录入自己的上游 Key 即可使用全部能力，无需部署。以下文档同时适用于 XSI Control 与自行部署的 XSI。
&lt;&#x2F;div&gt;
&lt;h2 id=&quot;xsi-shi-shen-me&quot;&gt;XSI 是什么&lt;&#x2F;h2&gt;
&lt;p&gt;&lt;strong&gt;XSI&lt;&#x2F;strong&gt; 是一个高性能、多租户的 &lt;strong&gt;AI API Router&lt;&#x2F;strong&gt;。它在一个入口上统一接入 OpenAI、Anthropic、Google、xAI、DeepSeek 等模型服务商，并在协议原生的前提下，提供路由与容错、账号与权限、计量与计费的完整能力。&lt;&#x2F;p&gt;
&lt;p&gt;应用只需持有一个 XSI API Key、修改一处 &lt;code&gt;base_url&lt;&#x2F;code&gt;，即可使用官方 SDK 与 Codex、Claude Code 等工具访问所有已接入的模型；上游 Key、路由策略、额度与价格由运营方在服务端统一治理。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;she-ji-yuan-ze&quot;&gt;设计原则&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;协议原生&lt;&#x2F;strong&gt;：不发明统一格式，完整保留 OpenAI Chat Completions、Responses（含 WebSocket 模式）、Anthropic Messages、Gemini 原生接口、Realtime 等协议的请求与响应语义。上游新增的参数与字段无需等待适配即可使用。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;性能优先&lt;&#x2F;strong&gt;：Go 实现，热路径全部在内存中完成，流式响应零缓冲透传，计量与结算异步执行。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;最少干预&lt;&#x2F;strong&gt;：只在路由、隔离与计费必需之处改写请求，其余原样透传。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;治理内建&lt;&#x2F;strong&gt;：账号树、额度、白名单、限速、计费与审计是核心模型的一部分，而不是外挂。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;he-xin-neng-li&quot;&gt;核心能力&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;能力&lt;&#x2F;th&gt;&lt;th&gt;说明&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;多协议接入&lt;&#x2F;td&gt;&lt;td&gt;OpenAI 兼容（Chat、Responses、Embeddings、Images、Audio、Videos、Files、Realtime、Live）、Anthropic Messages、Gemini 原生、DeepSeek 全系接口&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;多服务商&lt;&#x2F;td&gt;&lt;td&gt;OpenAI、Azure、Anthropic、Gemini、Vertex AI、xAI、DeepSeek、阿里云、火山方舟、智谱、Moonshot 等，以及任意 OpenAI 兼容服务&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;路由与容错&lt;&#x2F;td&gt;&lt;td&gt;按模型分组的 Key 池、模型映射、粘性会话、服务端自动重试、Key 休眠与自动禁用、分组切换与模型故障替换&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;多租户与账号树&lt;&#x2F;td&gt;&lt;td&gt;租户隔离、无限层级子账号、额度划转、继承与收窄、DNA 谱系查询&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;访问控制&lt;&#x2F;td&gt;&lt;td&gt;IP、接口与模型白名单，日&#x2F;月额度，账号级与模型级 RPM&#x2F;TPM 等六维限速&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;计量与计费&lt;&#x2F;td&gt;&lt;td&gt;Token、缓存读写、推理、图片、视频秒数、音频时长、搜索与工具调用分项计费；快速档位与长上下文分档；租户价格覆盖&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;双控制台&lt;&#x2F;td&gt;&lt;td&gt;配置管理（上游、路由、价格、通知）与账户管理（用量、账单、子账号、额度），中英文双语&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;安全&lt;&#x2F;td&gt;&lt;td&gt;上游 Key 按租户加密存储、凭证隔离、认证防护、注册防刷&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;gua-yong-chang-jing&quot;&gt;适用场景&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;企业内部 AI 网关&lt;&#x2F;strong&gt;：统一采购上游资源，按部门与项目分发额度、控制模型与成本，集中审计。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;AI API 服务&lt;&#x2F;strong&gt;：以自有品牌对外提供模型 API，按客户设定价格、额度与权限，支持多级分销。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;多租户 BYOK 平台&lt;&#x2F;strong&gt;：每个租户录入自己的上游 Key，独立管理账号、配置与价格。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;开发工具接入&lt;&#x2F;strong&gt;：为 Codex、Claude Code 等工具提供统一入口与用量治理。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;h2 id=&quot;chan-pin-yu-fu-wu&quot;&gt;产品与服务&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;&#x2F;th&gt;&lt;th&gt;定位&lt;&#x2F;th&gt;&lt;th&gt;地址&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;XSI&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;本项目：源码开放、商业授权的高性能 AI API Router，可自行部署&lt;&#x2F;td&gt;&lt;td&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi&quot;&gt;github.com&#x2F;xabcstack&#x2F;xsi&lt;&#x2F;a&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;XSI 官方站&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;XSI 的官方网站，同时运营基于 XSI 的商业 AI API 服务，注册即可调用&lt;&#x2F;td&gt;&lt;td&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;xsirouter.com&quot;&gt;xsirouter.com&lt;&#x2F;a&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;XSI Control&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;XSI 的多租户在线云服务：开通租户、录入自己的上游 Key 即可使用，无需部署&lt;&#x2F;td&gt;&lt;td&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;xsicontrol.com&quot;&gt;xsicontrol.com&lt;&#x2F;a&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;XAI Router &#x2F; YAI Router&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;在 XSI 基础上扩展订阅转 API 能力的商业 AI API 服务&lt;&#x2F;td&gt;&lt;td&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;xairouter.com&quot;&gt;xairouter.com&lt;&#x2F;a&gt; · &lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;yairouter.com&quot;&gt;yairouter.com&lt;&#x2F;a&gt;&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;h2 id=&quot;jia-gou-gai-lan&quot;&gt;架构概览&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;应用 &#x2F; SDK &#x2F; Codex &#x2F; Claude Code&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;            │  XSI API Key&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;            ▼&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;   ┌────────────────────────┐&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;   │ XSI                    │  认证 → 准入 → 模型映射 → Level 路由 → Key 池&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;   │ 数据面 + 控制面         │  ← 重试与故障转移 ← 计量与计费&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;   └──────┬──────────┬──────┘&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;          │          │&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;   PostgreSQL      Redis&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;          │&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;          ▼&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;OpenAI · Anthropic · Gemini · xAI · DeepSeek · Azure · Vertex · ...&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;详见《&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;architecture&#x2F;&quot;&gt;架构&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;shou-quan&quot;&gt;授权&lt;&#x2F;h2&gt;
&lt;p&gt;XSI 采用 &lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi&#x2F;blob&#x2F;main&#x2F;LICENSE&quot;&gt;XSI 源码可见许可证&lt;&#x2F;a&gt;：&lt;&#x2F;p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;个人非商业使用免费&lt;&#x2F;strong&gt;：学习、研究、实验与自用。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;strong&gt;企业生产使用及其他商业用途需取得商业授权&lt;&#x2F;strong&gt;：人民币 2,400 元／授权主体／年，包括个人运营的收费 API 或付费服务。&lt;&#x2F;li&gt;
&lt;li&gt;所有使用者须保留 &lt;code&gt;XSI by XABC Labs&lt;&#x2F;code&gt; 署名与原项目链接。&lt;&#x2F;li&gt;
&lt;li&gt;控制台默认的顶部广播位与推广卡片由 XABC Labs 提供内容，用于支持 XSI 的持续开发与运营，也是 XSI 能免费提供给个人使用的前提。未取得商业授权时须原样保留，商业授权可约定调整或关闭。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;详见&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi&#x2F;blob&#x2F;main&#x2F;COMMERCIAL-LICENSING.md&quot;&gt;商业授权说明&lt;&#x2F;a&gt;，咨询：&lt;a href=&quot;mailto:ywgx@xabcloud.com&quot;&gt;ywgx@xabcloud.com&lt;&#x2F;a&gt;。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;xia-yi-bu&quot;&gt;下一步&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;getting-started&#x2F;quick-start&#x2F;&quot;&gt;快速开始&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;docker-compose&#x2F;&quot;&gt;Docker Compose 部署&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;proxy&#x2F;&quot;&gt;Router API&lt;&#x2F;a&gt;&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>快速开始</title>
        <published>2025-03-01T08:00:00+00:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/getting-started/quick-start/"/>
        <id>https://xsicontrol.com/docs/getting-started/quick-start/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/getting-started/quick-start/">&lt;h2 id=&quot;xuan-ze-fang-shi&quot;&gt;选择方式&lt;&#x2F;h2&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;方式&lt;&#x2F;th&gt;&lt;th&gt;适合&lt;&#x2F;th&gt;&lt;th&gt;你需要准备&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;XSI Control 多租户云&lt;&#x2F;strong&gt; &lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;xsicontrol.com&quot;&gt;xsicontrol.com&lt;&#x2F;a&gt;&lt;&#x2F;td&gt;&lt;td&gt;使用自己的上游 Key，但不想部署&lt;&#x2F;td&gt;&lt;td&gt;邮箱、上游 Key&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;XSI 官方服务&lt;&#x2F;strong&gt; &lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;xsirouter.com&quot;&gt;xsirouter.com&lt;&#x2F;a&gt;&lt;&#x2F;td&gt;&lt;td&gt;直接调用模型，不想维护任何上游 Key&lt;&#x2F;td&gt;&lt;td&gt;邮箱&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;strong&gt;自行部署 XSI&lt;&#x2F;strong&gt;&lt;&#x2F;td&gt;&lt;td&gt;完全掌控数据与运营&lt;&#x2F;td&gt;&lt;td&gt;一台 Linux 主机、域名、上游 Key&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;三种方式的 API 完全一致，下文示例只需替换 &lt;code&gt;XSI_BASE_URL&lt;&#x2F;code&gt; 与 &lt;code&gt;XSI_API_KEY&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;lu-jing-yi-kai-tong-xsi-control-zu-hu&quot;&gt;路径一：开通 XSI Control 租户&lt;&#x2F;h2&gt;
&lt;p&gt;XSI Control 是 XSI 的多租户云服务。每个租户拥有独立的上游 Key 池、路由配置、价格与账号树。&lt;&#x2F;p&gt;
&lt;ol&gt;
&lt;li&gt;在 &lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;a.xsicontrol.com&quot;&gt;a.xsicontrol.com&lt;&#x2F;a&gt; 用邮箱注册，打开激活邮件中的链接完成激活，页面会显示你的租户所有者 API Key。&lt;&#x2F;li&gt;
&lt;li&gt;用该 Key 登录配置管理控制台（&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;a.xsicontrol.com&quot;&gt;a.xsicontrol.com&lt;&#x2F;a&gt;），在“模型服务”中录入你自己的上游 Key（BYOK），例如 OpenAI 放 Level 1、Anthropic 放 Level 2，系统会自动生成对应的 &lt;code&gt;LEVEL_MAPPER&lt;&#x2F;code&gt;。&lt;&#x2F;li&gt;
&lt;li&gt;在账户管理控制台（&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;m.xsicontrol.com&quot;&gt;m.xsicontrol.com&lt;&#x2F;a&gt;）为团队成员或客户创建子账号并分配额度，应用使用子账号的 Key 调用。&lt;&#x2F;li&gt;
&lt;li&gt;设置环境变量：&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;https:&#x2F;&#x2F;api.xsicontrol.com&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;sk-Xvs...&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;上游 Key 以租户密钥加密存储，租户密钥由你的 API Key 包裹，见《&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;architecture&#x2F;&quot;&gt;架构&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;lu-jing-er-zi-xing-bu-shu&quot;&gt;路径二：自行部署&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;git&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; clone https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi.git&lt;&#x2F;span&gt;&lt;span&gt; &amp;amp;&amp;amp;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; cd&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; xsi&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;umask 077&lt;&#x2F;span&gt;&lt;span&gt; &amp;amp;&amp;amp;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt; cp&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; docker-compose.example.yml docker-compose.yml&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;sed&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -i&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;s&#x2F;CHANGE_ME_POSTGRES_PASSWORD&#x2F;$(&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;openssl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; rand&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -hex 24&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;)&#x2F;g&amp;quot; docker-compose.yml&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;sed&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -i&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;s&#x2F;CHANGE_ME_ROOT_KEY&#x2F;sk-Xvs$(&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;openssl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; rand&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -hex 24&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt; |&lt;&#x2F;span&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt; cut&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -c1-45&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;)&#x2F;&amp;quot; docker-compose.yml&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #6A737D;&quot;&gt;# 编辑 docker-compose.yml：域名、root 邮箱与 SMTP&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;docker&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; compose up&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -d&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;随后：&lt;&#x2F;p&gt;
&lt;ol&gt;
&lt;li&gt;为 API 与两个控制台配置 HTTPS 反向代理，见《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;》。&lt;&#x2F;li&gt;
&lt;li&gt;用 root Key（&lt;code&gt;INIT_USERS&lt;&#x2F;code&gt; 中的 &lt;code&gt;sk-Xvs...&lt;&#x2F;code&gt;）登录配置管理控制台，在“模型服务”中添加上游 Key。&lt;&#x2F;li&gt;
&lt;li&gt;在账户管理控制台创建子账号并分配额度，用子账号的 Key 调用。&lt;&#x2F;li&gt;
&lt;&#x2F;ol&gt;
&lt;p&gt;完整步骤见《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;docker-compose&#x2F;&quot;&gt;Docker Compose 部署&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;https:&#x2F;&#x2F;api.example.com&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;export&lt;&#x2F;span&gt;&lt;span&gt; XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #F97583;&quot;&gt;=&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&amp;lt;子账号 Key&amp;gt;&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;fa-chu-di-yi-ge-qing-qiu&quot;&gt;发出第一个请求&lt;&#x2F;h2&gt;
&lt;p&gt;示例中的模型名需已在价格表中配置，且你的账号有权使用。可用 &lt;code&gt;GET &#x2F;v1&#x2F;models&lt;&#x2F;code&gt; 或 &lt;code&gt;GET &#x2F;x-pricing&lt;&#x2F;code&gt; 查看。&lt;&#x2F;p&gt;
&lt;h3 id=&quot;openai-responses&quot;&gt;OpenAI Responses&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;responses&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;model&amp;quot;: &amp;quot;gpt-6.2-sol&amp;quot;, &amp;quot;input&amp;quot;: &amp;quot;用一句话介绍你自己&amp;quot;}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h3 id=&quot;openai-chat-completions&quot;&gt;OpenAI Chat Completions&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;chat&#x2F;completions&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;model&amp;quot;: &amp;quot;gpt-6.2-sol&amp;quot;, &amp;quot;messages&amp;quot;: [{&amp;quot;role&amp;quot;: &amp;quot;user&amp;quot;, &amp;quot;content&amp;quot;: &amp;quot;用一句话介绍你自己&amp;quot;}]}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h3 id=&quot;anthropic-messages&quot;&gt;Anthropic Messages&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;messages&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;x-api-key: &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;anthropic-version: 2023-06-01&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;model&amp;quot;: &amp;quot;claude-sonnet-5-5&amp;quot;, &amp;quot;max_tokens&amp;quot;: 1024, &amp;quot;messages&amp;quot;: [{&amp;quot;role&amp;quot;: &amp;quot;user&amp;quot;, &amp;quot;content&amp;quot;: &amp;quot;用一句话介绍你自己&amp;quot;}]}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h3 id=&quot;gemini&quot;&gt;Gemini&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1beta&#x2F;models&#x2F;&lt;&#x2F;span&gt;&lt;span&gt;$GEMINI_MODEL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;:generateContent&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;x-goog-api-key: &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;contents&amp;quot;: [{&amp;quot;parts&amp;quot;: [{&amp;quot;text&amp;quot;: &amp;quot;用一句话介绍你自己&amp;quot;}]}]}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h3 id=&quot;deepseek&quot;&gt;DeepSeek&lt;&#x2F;h3&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;v1&#x2F;chat&#x2F;completions&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Content-Type: application&#x2F;json&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; \&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;
&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt;  -d&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;#39;{&amp;quot;model&amp;quot;: &amp;quot;deepseek-flash&amp;quot;, &amp;quot;messages&amp;quot;: [{&amp;quot;role&amp;quot;: &amp;quot;user&amp;quot;, &amp;quot;content&amp;quot;: &amp;quot;用一句话介绍你自己&amp;quot;}]}&amp;#39;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;&lt;h2 id=&quot;cha-kan-yong-liang&quot;&gt;查看用量&lt;&#x2F;h2&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;shellscript&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span style=&quot;color: #B392F0;&quot;&gt;curl&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;&lt;&#x2F;span&gt;&lt;span&gt;$XSI_BASE_URL&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&#x2F;dashboard&#x2F;live&amp;quot;&lt;&#x2F;span&gt;&lt;span style=&quot;color: #79B8FF;&quot;&gt; -H&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt; &amp;quot;Authorization: Bearer &lt;&#x2F;span&gt;&lt;span&gt;$XSI_API_KEY&lt;&#x2F;span&gt;&lt;span style=&quot;color: #9ECBFF;&quot;&gt;&amp;quot;&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;也可以在账户管理控制台查看实时用量、账单与模型明细。&lt;&#x2F;p&gt;
&lt;h2 id=&quot;xia-yi-bu&quot;&gt;下一步&lt;&#x2F;h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;getting-started&#x2F;sdk-integration&#x2F;&quot;&gt;SDK 集成&lt;&#x2F;a&gt;：Python、Node.js 与各类客户端&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;api-reference&#x2F;proxy&#x2F;&quot;&gt;Router API&lt;&#x2F;a&gt;：全部模型接口&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;user-hierarchy&#x2F;&quot;&gt;账号体系&lt;&#x2F;a&gt;：为团队或客户创建子账号&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;routing&#x2F;&quot;&gt;路由与故障转移&lt;&#x2F;a&gt;：配置多上游与容灾&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
</content>
        
    </entry>
    <entry xml:lang="zh">
        <title>常见问题</title>
        <published>2021-05-01T19:30:00+00:00</published>
        <updated>2026-11-19T00:00:00+08:00</updated>
        
        <author>
          <name>
            
              Unknown
            
          </name>
        </author>
        
        <link rel="alternate" type="text/html" href="https://xsicontrol.com/docs/help/faq/"/>
        <id>https://xsicontrol.com/docs/help/faq/</id>
        
        <content type="html" xml:base="https://xsicontrol.com/docs/help/faq/">&lt;h2 id=&quot;jie-ru&quot;&gt;接入&lt;&#x2F;h2&gt;
&lt;details&gt;
&lt;summary&gt;Base URL 应该写到哪一级？&lt;&#x2F;summary&gt;
&lt;p&gt;API 域名本身不含 &lt;code&gt;&#x2F;v1&lt;&#x2F;code&gt;。OpenAI SDK 与多数 OpenAI 兼容客户端填写 &lt;code&gt;https:&#x2F;&#x2F;&amp;lt;API 域名&amp;gt;&#x2F;v1&lt;&#x2F;code&gt;；Anthropic SDK 与 Claude Code 填写 &lt;code&gt;https:&#x2F;&#x2F;&amp;lt;API 域名&amp;gt;&lt;&#x2F;code&gt;；Gemini SDK 填写 &lt;code&gt;https:&#x2F;&#x2F;&amp;lt;API 域名&amp;gt;&lt;&#x2F;code&gt;。出现 &lt;code&gt;404&lt;&#x2F;code&gt; 时，通常是少写或多写了 &lt;code&gt;&#x2F;v1&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;为什么返回 401？&lt;&#x2F;summary&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;You didn&#x27;t provide an API key...&lt;&#x2F;code&gt;：没有携带 Key，或 Key 不是 &lt;code&gt;sk-Xvs&lt;&#x2F;code&gt; 开头的 51 位字符串。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;code&gt;Unauthorized&lt;&#x2F;code&gt;：Key 不存在或已被轮换。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;code&gt;Insufficient balance...&lt;&#x2F;code&gt;：余额低于冻结阈值，账号刚被冻结，充值后恢复。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;p&gt;如果错误正文是上游服务商的 JSON 格式，说明请求可能被直接发到了官方地址，请检查 &lt;code&gt;base_url&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;为什么提示模型无权使用，或者实际调用的模型和请求的不一样？&lt;&#x2F;summary&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;403 Access denied: You are not authorized to use the &#x27;&amp;lt;model&amp;gt;&#x27; model&lt;&#x2F;code&gt;：账号设置了模型白名单。&lt;&#x2F;li&gt;
&lt;li&gt;XSI 会按 &lt;code&gt;MODEL_MAPPER&lt;&#x2F;code&gt; 改写模型；未在价格表中的模型名还会被模糊匹配到同家族、版本最接近的已定价模型。请使用 &lt;code&gt;GET &#x2F;v1&#x2F;models&lt;&#x2F;code&gt; 或价格目录中的准确名称。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;流式输出卡住或一次性返回？&lt;&#x2F;summary&gt;
&lt;p&gt;通常是反向代理缓冲了响应。Nginx 需关闭 &lt;code&gt;proxy_buffering&lt;&#x2F;code&gt;，并把 &lt;code&gt;proxy_read_timeout&lt;&#x2F;code&gt; 设得足够长；经过 CDN 时注意其响应超时。见《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;开源项目不支持配置 base_url 怎么办？&lt;&#x2F;summary&gt;
&lt;p&gt;多数 SDK 支持通过环境变量设置地址（如 &lt;code&gt;OPENAI_BASE_URL&lt;&#x2F;code&gt;、&lt;code&gt;ANTHROPIC_BASE_URL&lt;&#x2F;code&gt;）。确实无法配置时，只能修改项目源码中的 API 地址。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;h2 id=&quot;ji-fei-yu-e-du&quot;&gt;计费与额度&lt;&#x2F;h2&gt;
&lt;details&gt;
&lt;summary&gt;如何计费？&lt;&#x2F;summary&gt;
&lt;p&gt;按上游返回的真实用量实时扣费，币种为人民币：&lt;&#x2F;p&gt;
&lt;pre class=&quot;giallo&quot; style=&quot;color: #E1E4E8; background-color: #24292E;&quot;&gt;&lt;code data-lang=&quot;plain&quot;&gt;&lt;span class=&quot;giallo-l&quot;&gt;&lt;span&gt;扣费 = 原价 × 用量 × 模型 Rates × 账号 Rates × 账号 Factor&lt;&#x2F;span&gt;&lt;&#x2F;span&gt;&lt;&#x2F;code&gt;&lt;&#x2F;pre&gt;
&lt;p&gt;价格表记录服务商原币种的原价，美元标价模型的 &lt;code&gt;Rates&lt;&#x2F;code&gt; 默认为 7。账号的最终单价可通过 &lt;code&gt;GET &#x2F;x-pricing&lt;&#x2F;code&gt;（携带 Key）的 &lt;code&gt;final&lt;&#x2F;code&gt; 字段查看。详见《&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;billing&#x2F;&quot;&gt;计费与价格&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;失败的请求收费吗？&lt;&#x2F;summary&gt;
&lt;p&gt;上游直接返回错误、且没有产生用量的普通 HTTP 请求不收费。被白名单或模型级限额拒绝的 POST、无法解析的请求体、调用了未定价的模型，会收取一次 &lt;code&gt;XAPI_FEE&lt;&#x2F;code&gt;（默认 ¥0.012），在账单中显示为 &lt;code&gt;XAPI&lt;&#x2F;code&gt;。中断或失败的请求按协议与已取得的用量结算：可靠的上游用量优先，缺失部分按已观察到的内容与会话历史估算；上游已接受的输入也可能产生费用。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;额度有有效期吗？&lt;&#x2F;summary&gt;
&lt;p&gt;有。每笔额度有独立的到期时间：充值额度默认 1 年，注册赠金 1 个月，子账号获得的划转额度沿用来源额度的到期时间。可在 &lt;code&gt;GET &#x2F;dashboard&#x2F;info&lt;&#x2F;code&gt; 的 &lt;code&gt;credit_balance&lt;&#x2F;code&gt; 中查看。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;账户还有余额，为什么提示余额不足或被暂停？&lt;&#x2F;summary&gt;
&lt;p&gt;余额不高于冻结阈值（&lt;code&gt;USER_MIN_BALANCE − 0.01&lt;&#x2F;code&gt;，部署模板为 ¥1.99）时，账号暂停调用：请求中首次发现余额不足返回 &lt;code&gt;401&lt;&#x2F;code&gt;，已被后台结算冻结时返回 &lt;code&gt;429&lt;&#x2F;code&gt;。充值后余额高于阈值即自动恢复。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;h2 id=&quot;xian-e-yu-xian-su&quot;&gt;限额与限速&lt;&#x2F;h2&gt;
&lt;details&gt;
&lt;summary&gt;为什么设置了 RPM &#x2F; DailyLimit 却没有生效？&lt;&#x2F;summary&gt;
&lt;p&gt;额度与限速只对 Role 2（严格）和 Role 3（订阅）账号生效。由 &lt;code&gt;INIT_USERS&lt;&#x2F;code&gt; 创建的 root 为 Role 0；单租户自助注册账号继承 root 的 Role（通常为 0），多租户注册默认 Role 1；子账号继承父账号。请由租户所有者把需要限制的账号设为 Role 2。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;429 之后要等多久恢复？&lt;&#x2F;summary&gt;
&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;命中的限制&lt;&#x2F;th&gt;&lt;th&gt;恢复&lt;&#x2F;th&gt;&lt;&#x2F;tr&gt;&lt;&#x2F;thead&gt;&lt;tbody&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;RPM&lt;&#x2F;code&gt;、&lt;code&gt;TPM&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;约 1 分钟&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;RPH&lt;&#x2F;code&gt;、&lt;code&gt;TPH&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;约 1 小时&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;RPD&lt;&#x2F;code&gt;、&lt;code&gt;TPD&lt;&#x2F;code&gt;、&lt;code&gt;DailyLimit&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;次日零点（服务器时区）&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;tr&gt;&lt;td&gt;&lt;code&gt;HardLimit&lt;&#x2F;code&gt;&lt;&#x2F;td&gt;&lt;td&gt;次月&lt;&#x2F;td&gt;&lt;&#x2F;tr&gt;
&lt;&#x2F;tbody&gt;&lt;&#x2F;table&gt;
&lt;p&gt;&lt;code&gt;RPD&lt;&#x2F;code&gt;&#x2F;&lt;code&gt;TPD&lt;&#x2F;code&gt; 是自然日额度，不是滚动 24 小时。请求数在通过准入时计数，已准入但上游失败的请求同样计入，冷却期内被拒绝的请求不会重复消耗配额；Token 在请求完成后累计，因此超额通常从下一次请求开始返回 &lt;code&gt;429&lt;&#x2F;code&gt;。客户端应使用指数退避，避免持续重试。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;为什么调用 &#x2F;x-users 返回 403？&lt;&#x2F;summary&gt;
&lt;p&gt;管理子账号需要同时满足：&lt;code&gt;TPD &amp;gt; 800000000&lt;&#x2F;code&gt;、具备子账号能力（&lt;code&gt;UserLimit &amp;gt; 0&lt;&#x2F;code&gt; 或已有子账号）、余额高于 &lt;code&gt;USER_API_BALANCE&lt;&#x2F;code&gt;（默认 ¥100）。错误正文会说明缺少哪一项。&lt;code&gt;GET &#x2F;dashboard&#x2F;status&lt;&#x2F;code&gt; 的 &lt;code&gt;manage&lt;&#x2F;code&gt; 字段可提前判断。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;子账号为什么不能再创建下级账号？&lt;&#x2F;summary&gt;
&lt;p&gt;父账号（非 root）自身的 &lt;code&gt;UserLimit&lt;&#x2F;code&gt; 小于 64 时，它创建的子账号 &lt;code&gt;UserLimit&lt;&#x2F;code&gt; 固定为 0，只能使用服务，不能继续分发。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;h2 id=&quot;bu-shu&quot;&gt;部署&lt;&#x2F;h2&gt;
&lt;details&gt;
&lt;summary&gt;控制台无法登录，浏览器提示跨域错误？&lt;&#x2F;summary&gt;
&lt;p&gt;XSI 不发送 CORS 响应头，控制台跨域调用 API 依赖反向代理为 API 域名添加 CORS 头并直接应答 &lt;code&gt;OPTIONS&lt;&#x2F;code&gt; 预检。参照《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;reverse-proxy&#x2F;&quot;&gt;反向代理&lt;&#x2F;a&gt;》的 Nginx 示例配置。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;请求返回 500 No available key？&lt;&#x2F;summary&gt;
&lt;p&gt;请求模型对应的 Level 中没有可用 Key：检查 &lt;code&gt;LEVEL_MAPPER&lt;&#x2F;code&gt; 是否把该模型映射到了正确的 Level，以及该 Level 的 Key 是否全部被禁用或处于休眠。可在配置管理控制台的“模型服务”或 &lt;code&gt;GET &#x2F;x-conf&lt;&#x2F;code&gt; 中查看休眠与禁用的 Key。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;修改了 docker-compose.yml 中的 root Key，为什么旧 Key 仍然有效？&lt;&#x2F;summary&gt;
&lt;p&gt;&lt;code&gt;INIT_USERS&lt;&#x2F;code&gt; 只创建不存在的账号，不会更新已有账号。轮换 root Key 请调用 &lt;code&gt;POST &#x2F;x-self&lt;&#x2F;code&gt;，确认短语为 &lt;code&gt;&amp;lt;日期&amp;gt;-ROTATE-ROOT&lt;&#x2F;code&gt;。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;如何调整默认模型价格？&lt;&#x2F;summary&gt;
&lt;p&gt;推荐使用租户 &lt;code&gt;PRICING&lt;&#x2F;code&gt; 覆盖，立即生效且无需重启；修改 &lt;code&gt;api&#x2F;pricing.json&lt;&#x2F;code&gt; 需要重新构建或挂载文件并重启。见《&lt;a href=&quot;&#x2F;docs&#x2F;concepts&#x2F;billing&#x2F;&quot;&gt;计费与价格&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;如何扩展到多台服务器？&lt;&#x2F;summary&gt;
&lt;p&gt;所有实例连接同一 PostgreSQL 与 Redis，设置 &lt;code&gt;SINGLE_MODE=false&lt;&#x2F;code&gt;，在负载均衡器后运行即可。见《&lt;a href=&quot;&#x2F;docs&#x2F;deployment&#x2F;operations&#x2F;#heng-xiang-kuo-zhan&quot;&gt;运维&lt;&#x2F;a&gt;》。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;h2 id=&quot;shou-quan&quot;&gt;授权&lt;&#x2F;h2&gt;
&lt;details&gt;
&lt;summary&gt;XSI 可以免费使用吗？&lt;&#x2F;summary&gt;
&lt;p&gt;个人非商业使用（学习、研究、实验与自用）免费。企业生产使用及其他商业用途（包括个人运营的收费 API 或付费服务）需取得商业授权，标准费用为人民币 2,400 元／授权主体／年。详见&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi&#x2F;blob&#x2F;main&#x2F;COMMERCIAL-LICENSING.md&quot;&gt;商业授权说明&lt;&#x2F;a&gt;。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;可以去掉控制台中的 XSI 署名吗？&lt;&#x2F;summary&gt;
&lt;p&gt;不可以。所有使用者（包括商业授权方）都须保留 &lt;code&gt;XSI by XABC Labs&lt;&#x2F;code&gt; 署名与原项目链接；有登录页的应用在登录页展示即可。可以自定义品牌名、布局与样式。详见 &lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi&#x2F;blob&#x2F;main&#x2F;NOTICE&quot;&gt;NOTICE&lt;&#x2F;a&gt;。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;可以关闭控制台顶部的广播和右侧的推广卡片吗？&lt;&#x2F;summary&gt;
&lt;p&gt;控制台默认的顶部广播位与推广卡片由 XABC Labs 提供内容，用于支持 XSI 的持续开发与运营，也是 XSI 能免费提供给个人使用的前提。免费使用时请原样保留，不要移除、隐藏、替换或修改它们；这项约束让我们能够持续免费地提供和维护 XSI。需要调整或关闭的企业，可以在&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;github.com&#x2F;xabcstack&#x2F;xsi&#x2F;blob&#x2F;main&#x2F;COMMERCIAL-LICENSING.md&quot;&gt;商业授权&lt;&#x2F;a&gt;中约定。&lt;&#x2F;p&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
&lt;details&gt;
&lt;summary&gt;不想自己部署，有托管服务吗？&lt;&#x2F;summary&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;xsirouter.com&quot;&gt;xsirouter.com&lt;&#x2F;a&gt;：XSI 官方运营的 AI API 服务，注册即可调用。&lt;&#x2F;li&gt;
&lt;li&gt;&lt;a rel=&quot;external&quot; href=&quot;https:&#x2F;&#x2F;xsicontrol.com&quot;&gt;xsicontrol.com&lt;&#x2F;a&gt;：XSI 多租户云服务，使用自己的上游 Key，无需部署。&lt;&#x2F;li&gt;
&lt;&#x2F;ul&gt;
&lt;&#x2F;details&gt;
&lt;br&#x2F;&gt;
</content>
        
    </entry>
</feed>
