# 概览 Cookbook 只回答一个问题：**怎么把 Praxis 接进你手上的东西**。概念与架构在[开发者文档](/docs/cloud)，端点与参数在 [API](/docs/api)，这里只放可复制的接入步骤。 ## 按工具选择接入方式 [#按工具选择接入方式] 绝大多数工具只需要三件事：Base URL、API Key、模型 ID。 | 你在用什么 | 推荐入口 | 状态 | | ------------------------------------------------ | ---------------------------------------- | -------- | | Claude Code、Codex、OpenCode 等编程 Agent | [编程 Agent](/docs/cookbook/coding-agents) | ✅ 3 篇已上线 | | OpenAI SDK、Anthropic SDK、Vercel AI SDK、LangChain | [SDK 与框架](/docs/cookbook/sdk) | ✅ 4 篇已上线 | | Cherry Studio 等聊天客户端 | [聊天客户端](/docs/cookbook/chat-clients) | ✅ 1 篇已上线 | | Cursor、Windsurf、Trae 等 IDE | [AI IDE](/docs/cookbook/ide) | 即将推出 | | n8n、Dify、FastGPT、Coze 等应用平台 | [智能体与工作流平台](/docs/cookbook/platforms) | ✅ 4 篇已上线 | | 端到端场景（RAG、多 Agent、批量处理） | [实战场景](/docs/cookbook/scenarios) | 即将推出 | | 从 OpenAI / Anthropic / OpenRouter 迁移过来 | [迁移指南](/docs/cookbook/migration) | ✅ 4 篇已上线 | ## 快速选路 [#快速选路] **不写代码，最快体验**：打开 [Praxis App](https://society.deepraxis.ai)，登录即用。 **不写代码，用你喜欢的客户端**：[Cherry Studio](/docs/cookbook/chat-clients/cherry-studio)（5 分钟接通，模型自动拉取）。 **写代码，最少改动**：[OpenAI SDK](/docs/cookbook/sdk/openai-sdk)（换一个 `baseURL` 就能用，`usage.cost` 直接返回费用）。 **终端编程，改代码 / 跑命令**：[Claude Code](/docs/cookbook/coding-agents/claude-code)（`settings.json` 一个文件搞定）。 **已有 OpenAI / Anthropic 代码要迁移**：看[迁移指南](/docs/cookbook/migration)——改一个地址就能迁过来。 # 编程 Agent 把 Praxis 接进终端编程智能体，用你的 Key 驱动——每个工具只需要 Base URL、API Key 和模型 ID 三件事。 所有客户端共用同一套 [前提](/docs/cloud/services/model/quickstart)：一个 `sk-praxis-` 开头的 Praxis API Key。 **协议速查**：Claude Code 走 Anthropic 协议（`/anthropic`）；Codex 走 OpenAI Responses 协议（`/openai/v1` + `wire_api: "responses"`）；其余大多数走 OpenAI 兼容协议（`/openai/v1`）。 **你是第一次接触编程 Agent？** 推荐从 [Claude Code](/docs/cookbook/coding-agents/claude-code) 开始——配置最少（一个 JSON 文件）、社区最活跃、文档最多。 # Claude Code 把 Praxis 接入 Claude Code，在终端里用你的 Key 驱动编程智能体——改代码、跑命令、答问题。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。 ## 你将完成 [#你将完成] * 在终端用 `claude` 命令调用 Praxis 的模型 * 完成标志：`claude -p "…"` 收到模型回复 * 预计耗时：**3 分钟**（不含 Node.js 安装） * 支持协议：Anthropic 兼容（Claude Code 原生协议） ## 前提 [#前提] 开始前逐项确认： * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，弹窗中**名称必填**，有效期默认 90 天（可改永久），点创建后立即复制保存；之后也随时可在 Key 列表行点「复制」重新获取完整 Key。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 * **Node.js 18 或更高**。终端运行 `node --version` 检查；没有就到 [nodejs.org](https://nodejs.org) 装 LTS 版。 * **安装 Claude Code**： ```bash npm install -g @anthropic-ai/claude-code ``` 期望：`claude --version` 输出版本号（本页以 2.1.211 为准）。 ## 配置 [#配置] **第 1 步：写入配置文件** 创建 `~/.claude/settings.json`（Windows 原生版为 `%USERPROFILE%\.claude\settings.json`），填入： ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.deepraxis.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "sk-praxis-你的Key" }, "model": "deepseek-flash" } ``` 两处说明： * `model` **必须指定**。Claude Code 默认请求的模型不在 Praxis 目录里，不指定会在首次对话时报「Model does not exist」。`deepseek-flash` 是平台示例模型——便宜、快、中英文都好；目录里的其他模型同样可填。 * 密钥写在 `ANTHROPIC_AUTH_TOKEN`，不是 `ANTHROPIC_API_KEY`——后者是官方直连时用的，配网关时无效。 期望：文件保存即生效，无需重启任何服务。 终端里查看 ~/.claude/settings.json 的实际内容 **第 2 步（可选）：临时会话不落盘** 不想把 Key 写进文件时，可以用一次性环境变量： ```bash ANTHROPIC_BASE_URL=https://api.deepraxis.com/anthropic \ ANTHROPIC_AUTH_TOKEN=sk-praxis-你的Key \ claude --model deepseek-flash -p "你好" ``` 期望：收到中文回复。Windows PowerShell 用户不必用此方式，直接按第 1 步写入配置文件即可。在代码项目目录里运行时，回复可能带上该项目 `AGENTS.md` / `CLAUDE.md` 的上下文口吻，属正常。 ## 验证 [#验证] ```bash claude -p "用中文回复四个字：连接成功" ``` 期望：终端直接输出 `连接成功`——**收到回复即接入成功**。 终端运行 claude -p 的真实输出 去掉 `-p` 进入交互模式，就是完整的编程智能体工作台。首次启动会先让你选界面主题，选完即进入主界面： claude 交互模式欢迎屏 也可以在命令行完成等价验证。先设置变量（不然照抄 curl 会得到 401）： ```bash export PRAXIS_API_KEY=sk-praxis-你的Key ``` 以下命令为 macOS / Linux / WSL（bash）写法。Windows PowerShell 用户：上面 `claude -p` 已收到回复即接入成功，可跳过；如需命令行验证，先执行 `$env:PRAXIS_API_KEY="你的Key"`，再把 curl 写成一行（去掉每行末尾的 `\`）。 ```bash curl https://api.deepraxis.com/anthropic/v1/messages \ -H "x-api-key: $PRAXIS_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{"model": "deepseek-flash", "max_tokens": 256, "messages": [{"role": "user", "content": "你好"}]}' ``` 期望：HTTP 200 即接入成功。`content` 中 `type` 为 `text` 的块是回复文本——`deepseek-flash` 是推理模型，前面可能先带一段 `thinking` 块，属正常。 最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。 控制台用量与费用页：deepseek-flash 的调用已逐笔记账 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | ------------------------------------------------------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | 首次对话报「issue with the selected model … may not exist」或 `Model … does not exist` | 没有指定 `model`，Claude Code 用了它的默认模型，而它不在 Praxis 目录里 | 在 `settings.json` 加 `"model"`，或命令加 `--model`，填[目录](https://console.deepraxis.ai/models)内的模型（如 `deepseek-flash`） | | 提示无效令牌 / 401 | Key 复制不完整或已吊销；或把 Key 写进了 `ANTHROPIC_API_KEY` | 重新完整复制（注意 `sk-praxis-` 前缀）；确认写在 `ANTHROPIC_AUTH_TOKEN`；仍失败到[控制台](https://console.deepraxis.ai/keys)重建一个 | | `Connection closed mid-response` | 网络瞬断 | 直接重试一次即可 | | `npm install -g` 报权限错误 | 系统 npm 全局目录不可写 | 设用户级前缀重装，或改用官方脚本安装（命令见下）；两法细节见 [npm 官方指南](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) | 官方安装脚本： ```bash curl -fsSL https://claude.ai/install.sh | bash ``` ## 进阶 [#进阶] * **查这段对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费 * **换模型**：改 `settings.json` 的 `model`（或临时用 `--model`）。要 Claude 系旗舰就填 `claude-opus-5`；要固定版本快照用 `deepseek-v4-flash`，`deepseek-flash` 则始终指向最新一代 Flash * **在项目里用**：进入代码目录直接运行 `claude`，它能读文件、改代码、执行命令——每一项动作都会先征求你的确认 ## 相关食谱 [#相关食谱] * [Codex](/docs/cookbook/coding-agents/codex) · [Cline](/docs/cookbook/coding-agents/cline) · [OpenCode](/docs/cookbook/coding-agents/opencode) * 偏好图形界面？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Chatbox](/docs/cookbook/chat-clients/chatbox) # Codex 把 Praxis 接入 Codex，在终端里用你的 Key 驱动 OpenAI 的编程智能体——改代码、跑命令、答问题。密钥只存环境变量，不落配置文件。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。 ## 你将完成 [#你将完成] * 在终端用 `codex` 命令调用 Praxis 的模型 * 完成标志：`codex exec "…"` 收到模型回复 * 预计耗时：**3–5 分钟**（不含 Node.js 安装） * 支持协议：OpenAI Responses（Codex 原生协议） ## 前提 [#前提] 开始前逐项确认： * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，弹窗中**名称必填**，有效期默认 90 天（可改永久），点创建后弹窗会展示完整 Key 一次——立即复制保存；之后也随时可在 Key 列表行点复制图标（悬停行时出现）重新获取完整 Key。若弹窗长时间停在「创建中…」，刷新列表确认 Key 已生成即可，行内复制同样能拿到完整 Key。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 * **Node.js 18 或更高**。终端运行 `node --version` 检查；没有就到 [nodejs.org](https://nodejs.org) 装 LTS 版。 * **安装 Codex CLI**： ```bash npm install -g @openai/codex ``` 期望：`codex --version` 输出 `codex-cli <版本号>`（本页以 0.162.1 为准）。 ## 配置 [#配置] **第 1 步：写配置文件** 创建 `~/.codex/config.toml`（Windows 为 `%USERPROFILE%\.codex\config.toml`）： ```toml model = "deepseek-flash" model_provider = "praxis" [model_providers.praxis] name = "Praxis" base_url = "https://api.deepraxis.com/openai/v1" env_key = "PRAXIS_API_KEY" wire_api = "responses" ``` 三处说明： * 密钥**不写进这个文件**——`env_key` 声明从环境变量 `PRAXIS_API_KEY` 读取，下一步设置。 * `wire_api` 必须是 `responses`：Codex 走的是 OpenAI Responses 协议，不是传统 chat completions。 * `model` 填目录内的模型 ID；`deepseek-flash` 是平台示例模型——便宜、快、中英文都好。 期望：文件保存后，下一次启动的 `codex` 命令即使用新配置（已开着的会话需退出重进）。 终端里查看 ~/.codex/config.toml 的实际内容 **第 2 步：设置密钥环境变量** macOS / Linux（WSL 同）： ```bash export PRAXIS_API_KEY=sk-praxis-你的Key ``` 想持久化就把这行加进 `~/.bashrc` 或 `~/.zshrc`。Windows PowerShell：`$env:PRAXIS_API_KEY="你的Key"`（或设置系统级环境变量后重开终端）。 期望：`echo $PRAXIS_API_KEY` 输出你的 Key（PowerShell 用 `echo $env:PRAXIS_API_KEY`）。 ## 验证 [#验证] 进入一个代码项目目录（git 仓库），运行： ```bash codex exec "用中文回复四个字：连接成功" ``` 期望：回复正文包含 `连接成功`，末尾附 tokens used 统计——**收到回复即接入成功**。首次运行可能提示「Model metadata for deepseek-flash not found … Defaulting to fallback metadata」，这是自定义模型的正常回退提示，不影响使用。 终端运行 codex exec 的真实输出 去掉 `exec` 直接运行 `codex`，进入交互式工作台（出现版本横幅与输入框即进入；本页不验证此项）。 也可以在命令行完成等价验证。先设置变量（不然照抄 curl 会得到 401）： ```bash export PRAXIS_API_KEY=sk-praxis-你的Key ``` ```bash curl https://api.deepraxis.com/openai/v1/responses \ -H "Authorization: Bearer $PRAXIS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "deepseek-flash", "input": "你好", "max_output_tokens": 256}' ``` 期望：HTTP 200 即接入成功。`output` 里 `type` 为 `text` 的块是回复文本——`deepseek-flash` 是推理模型，前面可能先带 `reasoning` 块，属正常。 > 上述命令为 macOS / Linux / WSL（bash）写法。Windows PowerShell 用户：上面的 `codex exec` 已成功即接入完成，可跳过；如需命令行验证，先 `$env:PRAXIS_API_KEY="你的Key"`，用 `curl.exe`（PowerShell 的 `curl` 是别名，语法不同），并把命令并成一行（去掉行尾 `\`）。 最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | ------------------------------------ | -------------------------------------------- | ------------------------------------------------------- | | 提示 `Model metadata … not found` | 自定义模型不在 Codex 内置元数据表里 | 正常回退提示，直接用；不影响对话与工具调用 | | 提示无效令牌 / 401 | `PRAXIS_API_KEY` 未导出、复制不完整，或改完 shellrc 没重开终端 | `echo $PRAXIS_API_KEY` 检查；重新完整复制；重开终端让配置生效 | | 报 `Not inside a trusted directory …` | 不在 git 仓库目录里运行 | 进项目目录运行；或临时加 `--skip-git-repo-check` | | 报 `unknown configuration field` | Codex 版本较旧，不认识新配置键 | `npm install -g @openai/codex` 升级后重试 | | 报模型不存在 | 模型 ID 与目录不一致 | 到[控制台 → 模型](https://console.deepraxis.ai/models)复制确切 ID | ## 进阶 [#进阶] * **查这段对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费 * **换模型**：改 `config.toml` 的 `model`，或运行 `codex -m <模型ID>`。可选 `deepseek-flash`、`deepseek-v4-flash`。Codex 只能使用声明了 Responses 协议的模型；在[模型目录](https://console.deepraxis.ai/models)打开模型详情，确认支持协议包含 Responses 后再选择。 * **在项目里用**：`codex` 交互模式能读文件、改代码、执行命令，敏感动作会先征求你的确认 ## 相关食谱 [#相关食谱] * [Claude Code](/docs/cookbook/coding-agents/claude-code)（Anthropic 协议姊妹篇）· [Cline](/docs/cookbook/coding-agents/cline) · [OpenCode](/docs/cookbook/coding-agents/opencode) * 偏好图形界面？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Chatbox](/docs/cookbook/chat-clients/chatbox) # Cline | | | | ---- | --------- | | 支持协议 | OpenAI 兼容 | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Cline 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # OpenCode 把 Praxis 接入 [OpenCode](https://opencode.ai)——开源终端编程智能体。项目里放一个 `opencode.json` 声明 provider，密钥走环境变量，`opencode run` 即通。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。 ## 你将完成 [#你将完成] * 在终端用 `opencode run` 调 Praxis 的模型 * 完成标志：`opencode run "…"` 收到模型回复 * 预计耗时：**3–5 分钟**（不含 Node.js 安装） * 支持协议：OpenAI 兼容（`/openai/v1`） ## 前提 [#前提] 开始前逐项确认： * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，名称必填，有效期可选 30/60/90 天或永久、默认 90 天；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 * **Node.js 18 或更高**（`node --version` 检查）。 * **安装 OpenCode**： ```bash npm install -g opencode-ai ``` 期望：`opencode --version` 输出版本号（本页以 1.19.0 为准）。若 npm 提示平台包问题，按提示补装对应平台包（Linux x64 为 `npm install -g opencode-linux-x64`）。 ## 配置 [#配置] **第 1 步：设置密钥环境变量** ```bash export PRAXIS_API_KEY=sk-praxis-你的Key ``` 想持久化就把这行加进 `~/.bashrc` 或 `~/.zshrc`。Windows PowerShell：`$env:PRAXIS_API_KEY="你的Key"`。 期望：`echo $PRAXIS_API_KEY` 输出你的 Key（PowerShell 用 `echo $env:PRAXIS_API_KEY`）。 **第 2 步：在项目里声明 provider** 进入你的代码项目目录，创建 `opencode.json`： ```json { "$schema": "https://opencode.ai/config.json", "provider": { "praxis": { "npm": "@ai-sdk/openai-compatible", "name": "Praxis", "options": { "baseURL": "https://api.deepraxis.com/openai/v1", "apiKey": "{env:PRAXIS_API_KEY}" }, "models": { "deepseek-flash": {} } } }, "model": "praxis/deepseek-flash" } ``` 三处说明： * `npm` 指定 OpenCode 用 `@ai-sdk/openai-compatible` 驱动对话——OpenCode 的 provider 体系建立在 AI SDK 之上，首次运行会自动装驱动。 * `apiKey` 用 `{env:PRAXIS_API_KEY}` 引用环境变量——密钥不落文件。 * 模型以 `provider/模型ID` 的命名空间引用；`deepseek-flash` 是平台示例模型。 期望：文件保存即生效。 终端里查看 opencode.json 的实际内容 ## 验证 [#验证] 在项目目录里运行： ```bash opencode run "用中文回复四个字：连接成功" ``` 期望：末行为模型回复 `连接成功`（其前有一行会话标题，如 `> build · deepseek-flash`）——**收到回复即接入成功**。去掉 `run` 直接运行 `opencode`，进入交互式终端界面。 终端运行 opencode run 的真实输出 也可以在命令行完成等价验证。以下命令为 macOS / Linux / WSL（bash）写法；Windows PowerShell 用户：上面的 `opencode run` 已成功即可跳过；如需命令行验证，先执行 `$env:PRAXIS_API_KEY="你的Key"`，用 `curl.exe`（PowerShell 的 `curl` 是别名，语法不同），并把命令并成一行（去掉行尾 `\`）。 ```bash export PRAXIS_API_KEY=sk-praxis-你的Key ``` ```bash curl https://api.deepraxis.com/openai/v1/chat/completions \ -H "Authorization: Bearer $PRAXIS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "deepseek-flash", "messages": [{"role": "user", "content": "你好"}]}' \ -w '\nHTTP %{http_code}\n' ``` 期望：HTTP 200 即接入成功，`choices[0].message.content` 是回复文本（响应出现 `reasoning` / `reasoning_details` 字段也正常——推理模型的思维链）。 最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。用量页默认按资源聚合展示，点「查看用量明细」或某资源行可逐笔核对。 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | -------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------- | | 401 / Missing authentication | 密钥未导出，或 `apiKey` 没用 `{env:…}` 引用 | 先 `echo $PRAXIS_API_KEY` 检查；确认 `apiKey` 写的是 `{env:PRAXIS_API_KEY}` | | 报 `EACCES`（mkdir `~/.local/share` 或 `~/.config` 等） | OpenCode 需要可写的用户数据目录，当前环境不可写 | 把 `XDG_DATA_HOME`/`XDG_CONFIG_HOME`/`XDG_STATE_HOME`/`XDG_CACHE_HOME` 指向可写目录后重试 | | 报平台包安装失败 | npm 没装对平台的二进制包 | 按报错提示补装（Linux x64 为 `opencode-linux-x64`） | | 404 / 路径不存在 | `baseURL` 写错 | 必须是 `https://api.deepraxis.com/openai/v1`（以 `/openai/v1` 结尾） | | 模型不存在 | 模型 ID 与目录不一致 | 到[控制台 → 模型 → 模型目录](https://console.deepraxis.ai/models)复制确切 ID | ## 进阶 [#进阶] * **查这次对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费 * **换模型**：在 `models` 里加目录中的其他 ID（如 `claude-opus-5`），并把 `model` 改成 `praxis/<新ID>` * **在项目里用**：交互模式能读文件、改代码、执行命令，敏感动作会先征求你的确认 ## 相关食谱 [#相关食谱] * [Claude Code](/docs/cookbook/coding-agents/claude-code) · [Codex](/docs/cookbook/coding-agents/codex)（姊妹篇） * 偏好 SDK 编程？看 [Vercel AI SDK](/docs/cookbook/sdk/vercel-ai-sdk)（OpenCode 的 provider 体系同源） # Kilo Code | | | | ---- | ---------------------------- | | 支持协议 | OpenAI 兼容 | | 备注 | 自动从 /openai/v1/models 拉取模型列表 | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Kilo Code 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # Roo Code | | | | ---- | --------- | | 支持协议 | OpenAI 兼容 | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Roo Code 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # Gemini CLI | | | | ---- | ------------------------ | | 支持协议 | Google (generateContent) | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Gemini CLI 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # Kimi Code | | | | ---- | --------- | | 支持协议 | OpenAI 兼容 | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Kimi Code 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # Qwen Code | | | | ---- | --------------------------------- | | 支持协议 | OpenAI 兼容 | | 备注 | Gemini CLI 分支，走 OPENAI\_BASE\_URL | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Qwen Code 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # AI IDE 把 Praxis 接进 AI 增强的 IDE，在编辑器里直接使用你的 Key 驱动模型——补全、对话、代码生成。 所有 IDE 共用同一套 [前提](/docs/cloud/services/model/quickstart)：一个 `sk-praxis-` 开头的 Praxis API Key。 **不想换 IDE？** 用终端编程 Agent（如 [Claude Code](/docs/cookbook/coding-agents/claude-code)）在你现有编辑器旁边工作，体验一样好。 # Trae | | | | ---- | ----------------- | | 支持协议 | OpenAI 兼容（国内版待核实） | | 备注 | 字节；自定义模型入口待核实 | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Trae 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # WorkBuddy / CodeBuddy | | | | ---- | ------------- | | 支持协议 | 待核实 | | 备注 | 腾讯；自定义模型入口待核实 | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 WorkBuddy / CodeBuddy 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # Cursor | | | | ---- | ------------------------ | | 支持协议 | OpenAI 兼容 | | 备注 | Override OpenAI Base URL | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Cursor 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # Windsurf | | | | ---- | --------- | | 支持协议 | OpenAI 兼容 | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Windsurf 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # 通义灵码 | | | | ---- | --- | | 支持协议 | 待核实 | | 备注 | 阿里 | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 通义灵码 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # 聊天客户端 把 Praxis 接进聊天客户端，用一个 Key 聊所有模型——全程不写代码，适合非开发者和快速体验。 所有客户端共用同一套 [前提](/docs/cloud/services/model/quickstart)：一个 `sk-praxis-` 开头的 Praxis API Key。 **你是第一次接触聊天客户端？** 推荐从 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) 开始——免费开源、模型目录自动拉取、中文界面友好、配置只需三步。 **想用但不想装客户端？** 直接用 Praxis App：打开 [society.deepraxis.ai](https://society.deepraxis.ai) 登录即用，零配置。 # Cherry Studio 把 Praxis 接入 Cherry Studio，用一个 Key 聊所有模型——全程不写代码。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成配置与验证。 ## 你将完成 [#你将完成] * 在 Cherry Studio 里直接使用 Praxis 的模型对话 * 完成标志：向 `deepseek-flash` 发送「你好」并收到回复 * 预计耗时：**5 分钟**（不含下载安装） * 支持协议：OpenAI 兼容（本页路线）/ Anthropic 兼容（见[进阶](#进阶)） ## 前提 [#前提] 开始前逐项确认： * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，弹窗中**名称必填**，有效期默认 90 天（可改永久），点创建后立即复制保存；之后也随时可在 Key 列表行点「复制」重新获取完整 Key。新账号自带 **$1 免费额度**，跑完本页绰绰有余。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 * **Cherry Studio 已安装**。从[官网](https://cherry-ai.com)下载（自动匹配系统），或到 [GitHub Releases](https://github.com/CherryHQ/cherry-studio/releases) 手选：Windows 选 `-setup.exe`（安装版）或 `-portable.exe`（免安装）；macOS 选 `.dmg`（Intel 芯片选 x64，Apple 芯片选 arm64）；Linux 选 `.AppImage`（下载后 `chmod +x` 加执行权限再运行）。 * **首次启动**：先选语言（默认 English，可切中文），欢迎页点「稍后设置」跳过登录即可使用。 * 本页以 v2.1.4 界面为准，菜单位置可能随版本微调。 ## 配置 [#配置] **第 1 步：打开模型服务设置** 主界面左下角的齿轮图标「设置」，再点左侧菜单「模型服务」。 期望：右侧出现提供商列表（OpenAI、硅基流动、智谱开放平台……）。 设置入口：左下角齿轮进入设置，左侧菜单选「模型服务」，右侧是提供商列表 **第 2 步：添加服务商，一次填齐名称、密钥、地址** 点提供商列表底部的「添加服务商」按钮，弹窗「添加自定义提供商」里填三处： | 字段 | 填什么 | | ----------------- | ------------------------------------- | | 提供商名称（必填） | `Praxis`（显示名，可任取） | | API 密钥 | `sk-praxis-` 开头的你的 Key | | 端点设置 → OpenAI 根地址 | `https://api.deepraxis.com/openai/v1` | 地址必须**以 `/v1` 结尾**——弹窗会实时显示「请求路径」预览，看到 `…/openai/v1/chat/completions` 即为正确。填完点「添加」。 期望：提供商列表末尾出现 Praxis 条目，卡片上密钥显示为掩码。 添加自定义提供商弹窗：名称填 Praxis，密钥与 OpenAI 根地址已填，下方显示请求路径预览 **第 3 步：添加模型** 添加成功后，Cherry Studio 会**自动拉取 Praxis 的模型目录**并弹出「选择模型」对话框。在列表中勾选 `deepseek-flash`——平台示例模型：便宜、快、中英文都好——点「添加所选模型」，应用会自动检测并启用。 期望：模型出现在 Praxis 的模型列表中，启用开关为开。 选择模型对话框：自动拉取的模型目录中勾选 deepseek-flash 拉取失败或列表为空时，点 Praxis 卡片上的「手动添加模型」，模型 ID 填 `deepseek-flash`，其余留空即可。 ## 验证 [#验证] 回到对话页，点**右上角的模型选择器**，切到 Praxis 下的 `deepseek-flash`，发送「你好」。 期望：几秒内收到一段中文回复——**收到回复即接入成功**。 对话页收到第一条回复：模型选择器显示 DeepSeek V4.1 Flash | Praxis 也可以在命令行完成等价验证。先设置变量（不然照抄 curl 会得到 401）： ```bash export PRAXIS_API_KEY=sk-praxis-你的Key ``` 以下命令为 macOS / Linux / WSL（bash）写法。Windows PowerShell 用户：界面已收到回复即接入成功，可跳过；如需命令行验证，先执行 `$env:PRAXIS_API_KEY="你的Key"`，再把 curl 写成一行（去掉每行末尾的 `\`）。 ```bash curl https://api.deepraxis.com/openai/v1/chat/completions \ -H "Authorization: Bearer $PRAXIS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "deepseek-flash", "messages": [{"role": "user", "content": "你好"}]}' ``` 期望：返回 HTTP 200，`choices[0].message.content` 是一段中文回复（响应里出现 `reasoning` 字段也正常——那是推理模型的思维链）。返回 `401` 是密钥问题，报「模型不存在」是 ID 拼写问题——对照下方常见问题。 最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | ----------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------- | | 提示无效令牌 / 401 | 密钥复制不完整，或 Key 已被吊销 | 重新完整复制（注意 `sk-praxis-` 前缀）；仍失败就到[控制台](https://console.deepraxis.ai/keys)重建一个 | | 首次发消息报「需要通过本地 API Gateway 桥接，网关已禁用」 | 本地网关默认关闭 | 按弹窗提示点「启用」，再重发一次 | | 模型列表拉取失败或为空 | API 地址路径不对 | 地址必须是 `https://api.deepraxis.com/openai/v1`（以 `/v1` 结尾，弹窗的请求路径预览可自查）；先跑上面 curl 分辨是网络还是配置问题；拉取不成用「手动添加模型」 | | 报「模型不存在」 | 模型 ID 与目录不一致 | 到[控制台 → 模型](https://console.deepraxis.ai/models)复制确切 ID | | 请求超时 / 无响应 | 本地网络环境 | 换网络或代理后重试；若 curl 同样超时，则是网络问题，与配置无关 | ## 进阶 [#进阶] * **查这段对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费 * **换模型**：模型列表里随时勾选添加其他模型，对话页随时切换。`deepseek-flash` 是滚动入口，始终指向最新一代 Flash（随官方更新换代）；需要固定版本时改用 `deepseek-v4-flash`（版本快照） * **用 Anthropic 协议接入**：在第 2 步弹窗的端点设置里改填 **Anthropic** 根地址 `https://api.deepraxis.com/anthropic`（不加 `/v1`，客户端自动拼 `/v1/messages`，弹窗预览可核对），其余步骤相同 ## 相关食谱 [#相关食谱] * [Chatbox](/docs/cookbook/chat-clients/chatbox) · [LobeHub](/docs/cookbook/chat-clients/lobehub) · [Open WebUI](/docs/cookbook/chat-clients/open-webui) * 从其他服务迁移过来？看[迁移指南](/docs/cookbook/migration) # Chatbox | | | | ---- | --------- | | 支持协议 | OpenAI 兼容 | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Chatbox 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # ChatWise | | | | ---- | --------- | | 支持协议 | OpenAI 兼容 | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 ChatWise 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # LobeHub 把 Praxis 接入 [LobeHub](https://lobehub.com)——开源的现代设计 AI 聊天界面，支持插件、多模型、语音。Docker 启动，浏览器里填两处即通。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。 ## 你将完成 [#你将完成] * 用 Docker 跑起一个 LobeHub 实例，接入 Praxis 的模型对话 * 完成标志：在聊天框发送「你好」并收到回复 * 预计耗时：**5 分钟**（不含 Docker 镜像下载） * 支持协议：OpenAI 兼容（`/openai/v1`） ## 前提 [#前提] * **Docker 已安装并运行**（`docker --version` 检查）。 * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 ## 安装与启动 [#安装与启动] **第 1 步：启动容器** ```bash docker run -d --name lobehub --restart always -p 3210:3210 lobehub/lobe-chat:latest ``` 期望：容器 ID 输出无报错，首次拉取约 1GB。 **第 2 步：打开浏览器** 访问 `http://localhost:3210`。期望：自动跳转到聊天页。 LobeHub 主界面 ## 配置 [#配置] **第 3 步：进入模型设置** 点击左侧边栏的设置图标（齿轮），选择「Language Model」。期望：看到 API Key 与 API Proxy Address 两个输入区域。 Settings → Language Model **第 4 步：填入 Praxis 连接** | 字段 | 填什么 | | ----------------- | ------------------------------------ | | API Key | `sk-praxis-` 开头的你的 Key | | API Proxy Address | `https://api.deepraxis.ai/openai/v1` | 点「Check」验证。期望：通过后在 Model List 勾选 `deepseek-flash`。 > 环境变量预设（免 UI 配置）： > > ```bash > docker run -d --name lobehub --restart always -p 3210:3210 \ > -e OPENAI_API_KEY=sk-praxis-你的Key \ > -e OPENAI_PROXY_URL=https://api.deepraxis.ai/openai/v1 \ > lobehub/lobe-chat:latest > ``` ## 验证 [#验证] 选模型，发「你好」。期望：收到回复即接入成功。 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | -------------------- | ----------------- | ---------------------------------------- | | `localhost:3210` 打不开 | 容器还在启动 | `docker logs lobehub` | | Check 不通过 | 地址少了 `/openai/v1` | 必须是 `https://api.deepraxis.ai/openai/v1` | | 401 | Key 不完整 | 重新复制 | | 模型列表为 OpenAI 默认 | 未自定义 Model List | 在 Language Model 页添加 `deepseek-flash` | ## 相关食谱 [#相关食谱] * [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Open WebUI](/docs/cookbook/chat-clients/open-webui) # Open WebUI 把 Praxis 接入 [Open WebUI](https://github.com/open-webui/open-webui)——最流行的开源自托管 AI 聊天界面。一条 Docker 命令启动，浏览器里配置连接，就能用 Praxis 的所有模型。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。 ## 你将完成 [#你将完成] * 用 Docker 跑起一个自托管的 Open WebUI 实例，接入 Praxis 的模型对话 * 完成标志：在聊天框发送「你好」并收到回复 * 预计耗时：**5 分钟**（不含 Docker 镜像下载） * 支持协议：OpenAI 兼容（`/openai/v1`） ## 前提 [#前提] 开始前逐项确认： * **Docker 已安装并运行**（`docker --version` 检查）。没有就到 [Docker 官网](https://docs.docker.com/get-docker/) 装。 * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，名称必填，有效期可选 30/60/90 天或永久、默认 90 天；创建成功弹窗会展示完整 Key 并带「复制 Key」。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 ## 安装与启动 [#安装与启动] **第 1 步：启动 Open WebUI 容器** ```bash docker run -d --name open-webui --restart always -p 3080:8080 ghcr.io/open-webui/open-webui:main ``` 期望：容器 ID 输出后无报错。首次运行会拉取镜像（约 2GB），需要几分钟。 **第 2 步：打开浏览器** 在浏览器访问 `http://localhost:3080`。 期望：看到 Open WebUI 欢迎页，带「Get started」按钮。 Open WebUI 首次访问的注册页 **第 3 步：创建管理员账号** 点「Get started」，填写 Name、Email、Password（这是本地管理员账号，与 Praxis 无关），点「Create Admin Account」。 期望：进入 Open WebUI 主界面——左侧是对话列表，中间是聊天框。 Open WebUI 主界面 ## 配置 [#配置] **第 4 步：进入连接设置** 点击右下角的**用户名**，选择「Admin Panel」→「Settings」→「Connections」。 期望：看到 OpenAI API 连接配置区域。 Admin Panel → Settings → Connections **第 5 步：填入 Praxis 连接** 在 **OpenAI API** 区域： | 字段 | 填什么 | | --- | ------------------------------------- | | URL | `https://api.deepraxis.com/openai/v1` | | Key | `sk-praxis-` 开头的你的 Key | 点「Save」。 期望：保存后返回聊天页，模型选择器中出现 Praxis 的模型列表。 > 也可以在启动容器时用环境变量预设连接（免 UI 配置）： > > ```bash > docker run -d --name open-webui --restart always -p 3080:8080 \ > -e OPENAI_API_BASE_URL=https://api.deepraxis.com/openai/v1 \ > -e OPENAI_API_KEY=sk-praxis-你的Key \ > ghcr.io/open-webui/open-webui:main > ``` ## 验证 [#验证] 回到聊天页，在顶部模型选择器中选一个模型（如 `deepseek-flash`），在输入框发送「你好」。 期望：几秒内收到回复——**收到回复即接入成功**。 最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | -------------------- | ---------------------------- | -------------------------------------------------------------- | | `localhost:3080` 打不开 | 容器还在启动中（首次约 1-2 分钟） | 等待后刷新；`docker logs open-webui` 查看进度 | | 模型列表为空 | 连接配置的 URL 少了 `/openai/v1` 后缀 | 必须是 `https://api.deepraxis.com/openai/v1` | | 401 / 无效令牌 | API Key 复制不完整 | 重新完整复制（注意 `sk-praxis-` 前缀） | | 模型不存在 | 模型 ID 与目录不一致 | 到[控制台 → 模型 → 模型目录](https://console.deepraxis.ai/models)复制确切 ID | | 容器反复重启 | 端口冲突或内存不足 | 检查 3080 端口是否被占用；确保 Docker 至少分配 2GB 内存 | ## 进阶 [#进阶] * **查这次对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费 * **换模型**：在 Open WebUI 的模型选择器中随时切换；`deepseek-flash` 是滚动入口始终指向最新一代 Flash * **多用户**：Open WebUI 支持多用户注册，在 Admin Panel → Users 管理权限 * **自定义界面**：Admin Panel → Settings → Interface 可改主题、语言（支持中文） * **数据持久化**：加 `-v open-webui:/app/backend/data` 挂载数据卷，容器重建后聊天记录不丢 ## 相关食谱 [#相关食谱] * [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio)（桌面客户端，不需要 Docker） * [Dify](/docs/cookbook/platforms/dify)（低代码平台，同样 Docker 部署） * 不想装任何东西？看 [Praxis App](/docs/app/install)：打开网址即用 # NextChat | | | | ---- | --------- | | 支持协议 | OpenAI 兼容 | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 NextChat 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # 智能体与工作流平台 把 Praxis 作为模型提供商接入低代码/无代码平台，在可视化画布里编排智能体和工作流。 所有平台共用同一套前提：一个 `sk-praxis-` 开头的 Praxis API Key。 **想写代码而不是拖积木？** 看 [SDK 与框架](/docs/cookbook/sdk)——用你熟悉的编程语言直连。 # Dify | | | | ---- | ------------------ | | 支持协议 | OpenAI 兼容 provider | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 Dify 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # Coze 把 Praxis 接入 [Coze](https://www.coze.cn)——字节跳动的智能体构建平台。Coze 支持自定义模型接入，在设置中添加 OpenAI 兼容模型即可使用 Praxis。 每一步都标了**期望结果**。 ## 你将完成 [#你将完成] * 在 Coze 中把 Praxis 配置为自定义模型，在智能体中使用 * 完成标志：智能体对话收到 Praxis 模型的回复 * 支持协议：OpenAI 兼容（`/openai/v1`） ## 前提 [#前提] * **一个 Coze 账号**（[coze.cn](https://www.coze.cn) 注册）。 * **一个 Praxis API Key**。到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建。见[快速开始](/docs/cloud/services/model/quickstart)。 ## 配置 [#配置] **第 1 步**：在 Coze 平台，点击左侧「模型」（或进入 Bot 编辑页 → 模型设置）。 **第 2 步**：选择「OpenAI 兼容」类型： | 字段 | 填什么 | | ------------ | ------------------------------------ | | 模型名称 | `deepseek-flash` | | API Base URL | `https://api.deepraxis.ai/openai/v1` | | API Key | `sk-praxis-` 开头的你的 Key | 点「测试连接」→「保存」。期望：测试通过，模型出现在可用列表。 ## 验证 [#验证] 创建 Bot，选 `deepseek-flash`，发「你好」。期望：收到回复即接入成功。 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | ---- | ------------------- | ------ | | 测试失败 | URL 少了 `/openai/v1` | 完整 URL | | 401 | Key 不完整 | 重新复制 | ## 相关食谱 [#相关食谱] * [Dify](/docs/cookbook/platforms/dify) · [n8n](/docs/cookbook/platforms/n8n) # n8n | | | | ---- | ----------- | | 支持协议 | OpenAI 兼容节点 | | 备注 | — | ## 前提 [#前提] 一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。 ## 配置 [#配置] （待补充：在 n8n 中填入 `https://api.deepraxis.com` 与 API Key 的步骤，配截图 / 30 秒视频。） ## 验证 [#验证] （待补充：接入成功的界面长什么样。） ## 常见问题 [#常见问题] （待补充：模型 id 怎么填、流式、国内网络。） # FastGPT 把 Praxis 接入 [FastGPT](https://fastgpt.in)——专注于知识库问答（RAG）的开源平台。Docker Compose 部署，在模型配置中添加 OpenAI 兼容渠道指向 Praxis，即可用你的模型做知识库问答。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。 ## 你将完成 [#你将完成] * 在 FastGPT 中把 Praxis 配置为模型渠道，在聊天中使用 * 完成标志：聊天中收到 Praxis 模型的回复 * 支持协议：OpenAI 兼容（`/openai/v1`） ## 前提 [#前提] * **Docker 与 Docker Compose 已安装**。 * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 ## 安装 [#安装] 完整部署见 [FastGPT 官方文档](https://doc.fastgpt.in/docs/installation/)。核心：`docker compose up -d`，访问 `http://localhost:3000`，用 `.env` 中的默认密码登录。 ## 配置 [#配置] **第 1 步：进入模型渠道设置** 点击左下角头像 →「账号」→「模型配置」。 **第 2 步：添加 OpenAI 兼容渠道** 点「新增渠道」，选「OpenAI」类型： | 字段 | 填什么 | | -------- | ------------------------------------ | | 渠道名称 | `Praxis` | | API Base | `https://api.deepraxis.ai/openai/v1` | | API Key | `sk-praxis-` 开头的你的 Key | | 模型 | `deepseek-flash` | 点「保存」。期望：渠道保存成功，模型测试通过。 ## 验证 [#验证] 聊天页选 `deepseek-flash`，发「你好」。期望：收到回复即接入成功。 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | -------------------- | ----------------- | ---------------------------------------- | | `localhost:3000` 打不开 | 容器启动中 | `docker compose logs -f` | | 测试不通过 | 地址少了 `/openai/v1` | 必须是 `https://api.deepraxis.ai/openai/v1` | | 401 | Key 不完整 | 重新复制 | | 知识库搜索无结果 | 嵌入模型未配置 | 另配 `text-embedding-3-small` | ## 相关食谱 [#相关食谱] * [Dify](/docs/cookbook/platforms/dify) · [n8n](/docs/cookbook/platforms/n8n) · [Open WebUI](/docs/cookbook/chat-clients/open-webui) # SDK 与框架 用你熟悉的 SDK 写代码调 Praxis 的模型——已有一切 OpenAI / Anthropic 代码不用换库，只改一个 `baseURL`。 所有 SDK 共用同一套 [前提](/docs/cloud/services/model/quickstart)：一个 `sk-praxis-` 开头的 Praxis API Key（走环境变量，不写进代码）。 **协议速查**：OpenAI 兼容走 `https://api.deepraxis.com/openai/v1`；Anthropic 兼容走 `https://api.deepraxis.com/anthropic`。 **你是第一次写 SDK 代码？** 推荐从 [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) 开始——生态最大、文档最多、三行核心代码就能跑通。 # OpenAI SDK 把 Praxis 接入 OpenAI 官方 SDK——已有一切 OpenAI 代码不用换库，只改一个 `baseURL`。本页 Node 与 Python 均实测（其余语言同形）。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、运行与验证。 ## 你将完成 [#你将完成] * 用 OpenAI SDK 调 Praxis 的模型，拿到回复与用量 * 完成标志：`hello.mjs` 打印中文回复与 `usage`，`stream.mjs` 逐字打印回复 * 预计耗时：**3 分钟**（不含 Node.js 安装） * 支持协议：OpenAI 兼容（`/openai/v1`） ## 前提 [#前提] 开始前逐项确认： * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，名称必填，有效期默认 90 天（可改永久），创建后立即复制保存；之后也随时可在 Key 列表行点复制图标重新获取完整 Key。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 * **Node.js 18 或更高**（`node --version` 检查；用 [Bun](https://bun.sh) 亦可）。 * **安装 SDK**：在项目目录里 ```bash npm install openai ``` 期望：安装无报错，`node -e "require('openai')"` 不抛错。 ## 第一个请求 [#第一个请求] 新建 `hello.mjs`，原样粘贴（把 Key 换成你的）： ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.deepraxis.com/openai/v1", apiKey: "sk-praxis-你的Key", }); const completion = await client.chat.completions.create({ model: "deepseek-flash", messages: [{ role: "user", content: "用一句话介绍你自己" }], }); console.log(completion.choices[0].message.content); console.log(completion.usage); ``` 运行： ```bash node hello.mjs ``` 期望：打印一段中文回复，随后是 `usage` 对象——注意里面有 `cost` 字段，**这次调用花了多少钱直接给你算好**（平台按次计费，控制台[用量与费用](https://console.deepraxis.ai/usage)同口径）。 终端运行示例脚本的真实输出 建议把 Key 放进环境变量而不是写进代码：`export PRAXIS_API_KEY=sk-praxis-…`（PowerShell：`$env:PRAXIS_API_KEY="…"`），然后 `apiKey: process.env.PRAXIS_API_KEY`。 ## Python 版 [#python-版] ```bash pip install openai ``` 先设置环境变量 `export PRAXIS_API_KEY=sk-praxis-你的Key`（PowerShell：`$env:PRAXIS_API_KEY="你的Key"`），再新建 `hello.py`： ```python import os from openai import OpenAI client = OpenAI( base_url="https://api.deepraxis.com/openai/v1", api_key=os.environ["PRAXIS_API_KEY"], ) completion = client.chat.completions.create( model="deepseek-flash", messages=[{"role": "user", "content": "用一句话介绍你自己"}], ) print(completion.choices[0].message.content) print(completion.usage) ``` 运行 `python3 hello.py`。期望：打印中文回复，随后是 `CompletionUsage`——其中 `cost` 字段直接给出本次费用。流式用法与 Node 同形（`stream=True` 后迭代 `delta.content`）。 Python 版示例的真实输出 ## 流式响应 [#流式响应] 新建 `stream.mjs`： ```javascript import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.deepraxis.com/openai/v1", apiKey: process.env.PRAXIS_API_KEY, }); const stream = await client.chat.completions.create({ model: "glm-5.3-flash", messages: [{ role: "user", content: "用两句话解释什么是 API" }], stream: true, }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content ?? ""); } console.log(); ``` 期望：回复逐字打印、以换行收尾——这就是流式。示例用 `glm-5.3-flash`；流式支持按模型路由而异，个别路由可能暂未开放，详见下方常见问题。 终端运行流式示例：回复逐字输出 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | ------------------------ | ------------------- | ------------------------------------------------------- | | 401 / 无效令牌 | Key 复制不完整或未设进环境变量 | 重新完整复制（注意 `sk-praxis-` 前缀）；用 `echo $PRAXIS_API_KEY` 检查 | | 400 `STREAMING_UNPROVEN` | 该模型暂未开放流式（逐路由开通，偶发） | 去掉 `stream: true`，或换个模型重试 | | 模型不存在 | 模型 ID 与目录不一致 | 到[控制台 → 模型](https://console.deepraxis.ai/models)复制确切 ID | | 连接超时 | 本地网络 | 重试或换网络；也可先用下面的命令测网关连通（期望 200） | 连通性自检： ```bash curl -sS https://api.deepraxis.com/openai/v1/models \ -H "Authorization: Bearer $PRAXIS_API_KEY" -o /dev/null -w "%{http_code}" ``` 期望输出 `200`。 ## 进阶 [#进阶] * **查这次调用花了多少钱**：非流式调用的 `usage.cost` 直接返回费用，无需自行按 token 换算；流式的费用在最后一个 chunk 的 `usage` 里（该 chunk 的 `choices` 为空、含 `cost`）——`stream_options: { include_usage: true }` 可加可不加，平台两种情况都会回；[控制台 → 用量与费用](https://console.deepraxis.ai/usage)有逐笔明细 * **列出可用模型**：`await client.models.list()`——和[控制台 → 模型](https://console.deepraxis.ai/models)同源 * **换模型**：改 `model` 字段即可；`deepseek-flash` 是滚动入口始终指向最新一代 Flash，`deepseek-v4-flash` 是固定版本快照 ## 相关食谱 [#相关食谱] * [Anthropic SDK](/docs/cookbook/sdk/anthropic-sdk)（Anthropic 协议姊妹篇）· [LangChain](/docs/cookbook/sdk/langchain) · [Vercel AI SDK](/docs/cookbook/sdk/vercel-ai-sdk) * 不想写代码？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Codex](/docs/cookbook/coding-agents/codex) # Anthropic SDK 把 Praxis 接入 Anthropic 官方 SDK——已有一切 Anthropic 代码不用换库，只改一个 `baseURL`。本页 Node 与 Python 均实测（其余语言同形）。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、运行与验证。 ## 你将完成 [#你将完成] * 用 Anthropic SDK 调 Praxis 的模型，拿到回复与用量 * 完成标志：`hello.mjs` 打印中文回复与 `usage`，`stream.mjs` 逐字打印回复 * 预计耗时：**3 分钟**（不含 Node.js 安装） * 支持协议：Anthropic 兼容（`/anthropic`） ## 前提 [#前提] 开始前逐项确认： * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，名称必填，有效期默认 90 天（可改永久）；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 * **Node.js 18 或更高**（`node --version` 检查；用 [Bun](https://bun.sh) 亦可）。 * **安装 SDK**——注意包名是 `@anthropic-ai/sdk`（npm 上的 `anthropic` 是同名的占位包，不是它）： ```bash npm install @anthropic-ai/sdk ``` 期望：安装无报错。 ## 第一个请求 [#第一个请求] 先把 Key 放进环境变量（`export PRAXIS_API_KEY=sk-praxis-…`；PowerShell：`$env:PRAXIS_API_KEY="…"`），再新建 `hello.mjs`： ```javascript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ baseURL: "https://api.deepraxis.com/anthropic", apiKey: "sk-praxis-你的Key", }); const message = await client.messages.create({ model: "deepseek-flash", max_tokens: 256, messages: [{ role: "user", content: "用一句话介绍你自己" }], }); console.log(message.content.find((b) => b.type === "text")?.text); console.log(message.usage); ``` 运行： ```bash node hello.mjs ``` 期望：打印一段中文回复，随后是 `usage`——至少包含 `input_tokens` / `output_tokens`，SDK 还会附带缓存、服务分层等字段。两处注意：**`max_tokens` 必填**（Anthropic 协议的要求）；`content` 是块数组，取 `type` 为 `text` 的块是回复文本——推理模型前面可能先带 `thinking` 块。 终端运行示例脚本的真实输出 ## Python 版 [#python-版] ```bash pip install anthropic ``` 新建 `hello.py`： ```python import os from anthropic import Anthropic client = Anthropic( base_url="https://api.deepraxis.com/anthropic", api_key=os.environ["PRAXIS_API_KEY"], ) message = client.messages.create( model="deepseek-flash", max_tokens=256, messages=[{"role": "user", "content": "用一句话介绍你自己"}], ) print(next(b.text for b in message.content if b.type == "text")) print(message.usage) ``` 运行 `python3 hello.py`。期望：打印中文回复，随后是 `Usage`——同样必填 `max_tokens`，`content` 是块数组。流式用 `client.messages.stream(...)` 上下文管理器，与 Node 同形。 Python 版示例的真实输出 ## 流式响应 [#流式响应] 新建 `stream.mjs`： ```javascript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ baseURL: "https://api.deepraxis.com/anthropic", apiKey: process.env.PRAXIS_API_KEY, }); const stream = client.messages.stream({ model: "deepseek-flash", max_tokens: 256, messages: [{ role: "user", content: "用两句话解释什么是 API" }], }); for await (const event of stream) { if (event.type === "content_block_delta" && event.delta.type === "text_delta") { process.stdout.write(event.delta.text); } } console.log(); ``` 期望：回复逐字打印、以换行收尾。流式支持按模型路由而异，个别路由可能暂未开放（报 `STREAMING_UNPROVEN` 时去掉流式或换模型重试）。 终端运行流式示例：回复逐字输出 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | ------------------------------------------------------------------------------ | ----------------- | ------------------------------------------------------- | | 导入名为 `anthropic` 的包后运行失败（报错指向 `node_modules/anthropic/index.js` 缺失或 `main` 无效） | 装到了 npm 上的同名占位包 | 卸掉重装正主：卸载 `anthropic` 后安装 `@anthropic-ai/sdk` | | 401 / 无效令牌 | Key 复制不完整或未设进环境变量 | 重新完整复制（注意 `sk-praxis-` 前缀）；用 `echo $PRAXIS_API_KEY` 检查 | | 400 提示缺 `max_tokens` | Anthropic 协议必填该参数 | 在 `messages.create` 里加上 `max_tokens`（如 256） | | 400 `STREAMING_UNPROVEN` | 该模型路由暂未开放流式 | 去掉流式用普通调用，或换个模型重试 | | 模型不存在 | 模型 ID 与目录不一致 | 到[控制台 → 模型](https://console.deepraxis.ai/models)复制确切 ID | ## 进阶 [#进阶] * **查这次调用花了多少钱**：非流式 `message.usage.cost`（Python SDK）直接返回费用；流式在 `message_delta` 事件的 `usage.cost` 上（`get_final_message().usage` 不带该字段）。JS SDK 的 `Usage` 类型不声明 cost（运行时字段仍在，`as any` 可读），Node 用户也可看[控制台 → 用量与费用](https://console.deepraxis.ai/usage)逐笔明细，或走 [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) * **换模型**：改 `model` 字段即可，Claude 系旗舰填 `claude-opus-5`；`deepseek-flash` 是滚动入口始终指向最新一代 Flash * **拿思维链**：推理模型的 `content` 里 `type` 为 `thinking` 的块即思维链，按需读取 ## 相关食谱 [#相关食谱] * [OpenAI SDK](/docs/cookbook/sdk/openai-sdk)（OpenAI 协议姊妹篇）· [LangChain](/docs/cookbook/sdk/langchain) · [Vercel AI SDK](/docs/cookbook/sdk/vercel-ai-sdk) * 不想写代码？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Claude Code](/docs/cookbook/coding-agents/claude-code) # Vercel AI SDK 把 Praxis 接入 [Vercel AI SDK](https://ai-sdk.dev)——React/Vue/Svelte 里做 AI 应用的事实标准库。自定义 provider 两个参数即接通，`generateText` / `streamText` 及全家能力照常用。本页以 Node 实测。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、运行与验证。 ## 你将完成 [#你将完成] * 用 AI SDK 的 `generateText` / `streamText` 调 Praxis 的模型 * 完成标志：`hello.mjs` 打印中文回复与 `usage`，`stream.mjs` 逐字打印回复 * 预计耗时：**3–5 分钟**（不含 Node.js 安装） * 支持协议：OpenAI 兼容（`/openai/v1`） ## 前提 [#前提] 开始前逐项确认： * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，名称必填，有效期默认 90 天（可改永久）；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 * **Node.js 18 或更高**（`node --version` 检查；用 [Bun](https://bun.sh) 亦可）。 * **安装 SDK**： ```bash npm install ai @ai-sdk/openai ``` 期望：安装无报错。空目录直接装即可，无需先 `npm init`。 ## 第一个请求 [#第一个请求] 先把 Key 放进环境变量（`export PRAXIS_API_KEY=sk-praxis-…`；PowerShell：`$env:PRAXIS_API_KEY="…"`），再新建 `hello.mjs`： ```javascript import { createOpenAI } from "@ai-sdk/openai"; import { generateText } from "ai"; const praxis = createOpenAI({ baseURL: "https://api.deepraxis.com/openai/v1", apiKey: process.env.PRAXIS_API_KEY, }); const { text, usage } = await generateText({ model: praxis("deepseek-flash"), prompt: "用一句话介绍你自己", }); console.log(text); console.log(usage); ``` 运行： ```bash node hello.mjs ``` 期望：打印一段中文回复，随后是 `usage` 对象——驼峰形态，含 `inputTokens` / `outputTokens` / `totalTokens` 与 `raw` 原始字段；推理模型的 `reasoningTokens` 在 `outputTokenDetails` 明细里。 终端运行示例脚本的真实输出 ## 流式响应 [#流式响应] 新建 `stream.mjs`： ```javascript import { createOpenAI } from "@ai-sdk/openai"; import { streamText } from "ai"; const praxis = createOpenAI({ baseURL: "https://api.deepraxis.com/openai/v1", apiKey: process.env.PRAXIS_API_KEY, }); const stream = streamText({ model: praxis("deepseek-flash"), prompt: "用两句话解释什么是 API", }); for await (const chunk of stream.textStream) { process.stdout.write(chunk); } console.log(); ``` 期望：回复逐字打印、以换行收尾。流式支持因模型及其上游通道而异，个别可能暂未开放（报 `STREAMING_UNPROVEN` 时去掉流式或换模型重试）。 终端运行流式示例：回复逐字输出 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | ------------------------ | ---------------------------- | -------------------------------------------------------------- | | 401 / 无效令牌 | Key 复制不完整或未设进环境变量 | 重新完整复制（注意 `sk-praxis-` 前缀）；用 `echo $PRAXIS_API_KEY` 检查 | | 404 / 路径不存在 | `baseURL` 少了 `/openai/v1` 后缀 | 必须是 `https://api.deepraxis.com/openai/v1`（以 `/v1` 结尾） | | 400 `STREAMING_UNPROVEN` | 该模型路由暂未开放流式 | 去掉流式用 `generateText`，或换个模型重试 | | 模型不存在 | 模型 ID 与目录不一致 | 到[控制台 → 模型 → 模型目录](https://console.deepraxis.ai/models)复制确切 ID | ## 进阶 [#进阶] * **前端聊天组件**：AI SDK 的 `useChat` 等 React Hooks 与后端 `streamText` 天然配套（见 [AI SDK 官方文档](https://ai-sdk.dev)），provider 写法与本页相同 * **查这次调用花了多少钱**：AI SDK 的 `usage` 不带费用；用 [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) 那条路 `usage.cost` 直接返回，或看[控制台 → 用量与费用](https://console.deepraxis.ai/usage) * **换模型**：改 `praxis("…")` 里的模型 ID；`deepseek-flash` 是滚动入口始终指向最新一代 Flash ## 相关食谱 [#相关食谱] * [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) · [Anthropic SDK](/docs/cookbook/sdk/anthropic-sdk) · [LangChain](/docs/cookbook/sdk/langchain) * 不想写代码？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Codex](/docs/cookbook/coding-agents/codex) # LangChain 把 Praxis 接入 [LangChain](https://js.langchain.com)（JS/TS 版）——链、记忆、工具全家桶照常用，模型侧只改一个 `baseURL`。本页以 Node 实测。 每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、运行与验证。 ## 你将完成 [#你将完成] * 用 LangChain 的 `ChatOpenAI` 调 Praxis 的模型，拿到回复与用量 * 完成标志：`hello.mjs` 打印中文回复与用量，`stream.mjs` 逐字打印回复 * 预计耗时：**3–5 分钟**（不含 Node.js 安装） * 支持协议：OpenAI 兼容（`/openai/v1`） ## 前提 [#前提] 开始前逐项确认： * **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，名称必填，有效期可选 30/60/90 天或永久，默认 90 天；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。 * **Node.js 18 或更高**（`node --version` 检查；用 [Bun](https://bun.sh) 亦可）。 * **安装 SDK**： ```bash npm install @langchain/openai ``` 期望：安装无报错。空目录直接装即可（npm 会在当前目录生成 package.json、package-lock.json 与 node\_modules）；需要链、提示词模板、输出解析器时再 `npm install langchain`。 ## 第一个请求 [#第一个请求] 先把 Key 放进环境变量（`export PRAXIS_API_KEY=sk-praxis-…`；PowerShell：`$env:PRAXIS_API_KEY="…"`），再新建 `hello.mjs`： ```javascript import { ChatOpenAI } from "@langchain/openai"; const model = new ChatOpenAI({ model: "deepseek-flash", configuration: { baseURL: "https://api.deepraxis.com/openai/v1", apiKey: process.env.PRAXIS_API_KEY, }, }); const res = await model.invoke("用一句话介绍你自己"); console.log(res.content); console.log(res.usage_metadata); ``` 运行： ```bash node hello.mjs ``` 期望：打印一段中文回复，随后是用量对象（`input_tokens` / `output_tokens` / `total_tokens`；推理 token 数见 `output_token_details.reasoning`）。注意与 OpenAI 官方 SDK 的差别：**地址与密钥写在 `configuration` 嵌套对象里**，不是顶层字段。 终端运行示例脚本的真实输出 ## 流式响应 [#流式响应] 新建 `stream.mjs`： ```javascript import { ChatOpenAI } from "@langchain/openai"; const model = new ChatOpenAI({ model: "deepseek-flash", configuration: { baseURL: "https://api.deepraxis.com/openai/v1", apiKey: process.env.PRAXIS_API_KEY, }, }); const stream = await model.stream("用两句话解释什么是 API"); for await (const chunk of stream) { process.stdout.write(chunk.content); } console.log(); ``` 期望：回复逐字打印、以换行收尾。流式支持因模型及其上游通道而异，个别可能暂未开放（报 `STREAMING_UNPROVEN` 时去掉流式或换模型重试）。 终端运行流式示例：回复逐字输出 ## 常见问题 [#常见问题] | 症状 | 原因 | 解法 | | ------------------------ | ---------------------------- | -------------------------------------------------------------- | | 401 / 无效令牌 | Key 复制不完整或未设进环境变量 | 重新完整复制（注意 `sk-praxis-` 前缀）；用 `echo $PRAXIS_API_KEY` 检查 | | 404 / 路径不存在 | `baseURL` 少了 `/openai/v1` 后缀 | 必须是 `https://api.deepraxis.com/openai/v1`（以 `/v1` 结尾） | | 配置不生效 | 地址写在了顶层而不是 `configuration` 里 | 移进 `configuration: { baseURL, apiKey }` | | 400 `STREAMING_UNPROVEN` | 该模型暂未开放流式 | 改用 `invoke`，或换个模型重试 | | 模型不存在 | 模型 ID 与目录不一致 | 到[控制台 → 模型 → 模型目录](https://console.deepraxis.ai/models)复制确切 ID | ## 进阶 [#进阶] * **链式调用**：`model.pipe(...)` 接提示词模板、输出解析器即成链——Praxis 侧无需任何额外配置 * **查这次调用花了多少钱**：LangChain 的用量不带费用；用 [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) 那条路 `usage.cost` 直接返回，或看[控制台 → 用量与费用](https://console.deepraxis.ai/usage) * **换模型**：改 `model` 字段；`deepseek-flash` 是滚动入口始终指向最新一代 Flash ## 相关食谱 [#相关食谱] * [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) · [Anthropic SDK](/docs/cookbook/sdk/anthropic-sdk) · [Vercel AI SDK](/docs/cookbook/sdk/vercel-ai-sdk) * 不想写代码？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Claude Code](/docs/cookbook/coding-agents/claude-code) # 迁移指南 # 从 OpenAI 官方迁移 保留 OpenAI SDK，改地址、Key 和模型 ID，先迁移一次 Chat Completions 请求。更换模型会改变回答行为；这不是让 DeepSeek 变成 GPT-4o。 ```diff client = OpenAI( - base_url="https://api.openai.com/v1", - api_key=os.environ["OPENAI_API_KEY"], + base_url="https://api.deepraxis.com/openai/v1", + api_key=os.environ["PRAXIS_API_KEY"], ) -model = "gpt-4o" +model = "deepseek-flash" ``` ## 1. 准备 [#1-准备] 需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。 ```bash test -n "${PRAXIS_API_KEY:-}" ``` 期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。 ## 2. 选择模型 ID [#2-选择模型-id] 下表是迁移选择，不是别名或等价效果承诺。可用性核对于 2026-10-12；切换流量前再查[模型目录](https://console.deepraxis.ai/models)。 | 原 ID | Praxis 选择 | 需要注意 | | --------------------------- | ---------------------------------- | --------------------------------- | | `gpt-4o`、`gpt-4o-mini` | `deepseek-flash` | 原 ID 不存在；重新评估提示词、工具与回答质量 | | `gpt-4.1`、`o3-mini`、`gpt-5` | `deepseek-flash` | 不自动映射；原 ID 返回 404 | | 必须使用 OpenAI 系模型 | `gpt-5.6-sol` | 可用 Chat Completions，不支持 Responses | | 原代码使用 Responses | `deepseek-flash` 或 `glm-5.3-flash` | 当前可用的 Responses 选择 | 使用 Responses 时，确认选定 ID 出现在 `GET /openai/v1/models?api=responses`（Python：`client.models.list(extra_query={"api": "responses"})`）。也可查看 `GET /model/v1/models` 或 `GET /model/v1/models/{id}` 的 `supported_apis`，确认包含 `openai.responses`。OpenAI 面还可按 `chat`、`embeddings`、`images`、`audio`、`videos` 筛选；逗号分隔表示匹配任一协议。 ## 行为差异 [#行为差异] * 同协议请求按原协议转发，不代表所有官方模型、端点、字段都可用。 * 列表内的模型仍可能对某个操作返回 `404 model_protocol_not_offered`；Chat 与 Responses 要分别确认。 * 切流量前用自己的提示词检查流式、工具执行、结构化输出和思考行为。字段差异以 [Chat Completions](/docs/api/compatible/openai/createChatCompletion) 与 [Responses](/docs/api/compatible/openai/createResponse) 为准。 * 原服务的文件、会话与响应 ID 不随地址修改自动迁移；保留源数据，并重建应用需要的资源。 * Chat 的 `usage.cost` 是实付金额；Responses 和 Messages 目前不返回该字段。收到 `X-Praxis-Generation-Id` 时，可按 [生成记录 API](/docs/api/native/model/getGeneration) 用 `GET /model/v1/generation?id=生成ID` 查费用（记录可能延迟几秒）。若响应没有该头，去[控制台 → 用量与费用](https://console.deepraxis.ai/usage)查本次调用；不要把响应正文的 `id` 或 `X-Request-Id` 当成生成 ID，也不要将缺失费用当成零。 ## 不支持的端点与替代 [#不支持的端点与替代] 以下路径相对于 `/openai/v1`，调用返回 404。替代流程不保证与原端点等价；有依赖时先拆分调用，保留原服务。 | 原端点 | 迁移选择 | | -------------------- | --------------------------------------- | | `moderations` | 无直接替代，继续使用原审核服务 | | `batches` | 由应用逐次调用并控制并发 | | `fine_tuning` | 选已有模型；保留原微调流程 | | `assistants` | 重新组织为 Responses / Conversations 与应用工具循环 | | `completions` | 改用 `chat/completions` 和 `messages` | | `audio/translations` | 先转写，再用对话翻译 | | `uploads` | 改用 `files`；核对文件大小与用途限制 | | `images/variations` | 用 `images/edits` 提交图片与编辑提示词，重新评估效果 | 可用端点包括 `chat/completions`、`responses`、`embeddings`、`images/generations`、`images/edits`、`audio/speech`、`audio/transcriptions`、`videos`、`files`、`models`。可用端点不表示每个模型都支持该能力；具体操作与限制见 [OpenAI API 参考](/docs/api/compatible/openai)。 ## 3. 验证一次请求 [#3-验证一次请求] 设置好 `PRAXIS_API_KEY` 后运行以下完整示例： ```bash unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy uv run -q --no-project --with openai --with anthropic python - <<'PY' import os from openai import OpenAI client = OpenAI( base_url="https://api.deepraxis.com/openai/v1", api_key=os.environ["PRAXIS_API_KEY"], timeout=90.0, max_retries=0, ) models = client.models.list(extra_query={"api": "chat"}) assert "deepseek-flash" in {m.id for m in models.data} raw = client.chat.completions.with_raw_response.create( model="deepseek-flash", messages=[{"role": "user", "content": "Reply OK."}], max_tokens=1024, ) reply = raw.parse() text = reply.choices[0].message.content print("HTTP", raw.status_code) print("X-Request-Id:", raw.headers.get("x-request-id")) print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id")) print(text) assert raw.status_code == 200 and text and text.strip() assert raw.headers.get("x-request-id") PY ``` 期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。 ## 失败分支 [#失败分支] | 实测报错 | 处理 | | -------------------------------------- | -------------------------------------------------------- | | `404`，`Model "gpt-4o" does not exist.` | 地址与 Key 之外也要改模型；使用目录中的完整 ID | | `404 model_protocol_not_offered` | 换支持该操作的模型；Responses 选 `deepseek-flash` 或 `glm-5.3-flash` | | 上表端点返回 `404 Not Found` | 按表替代，或让该请求继续使用原服务 | ## 4. 回滚 [#4-回滚] 一起恢复三个原值：`https://api.openai.com/v1`、`OPENAI_API_KEY` 中的原 Key、原模型 ID。移除 Praxis 专有请求字段，恢复原资源 ID。重启应用让客户端加载旧配置，再跑原有冒烟请求并保留请求 ID。 期望：原端点成功返回可用正文。配置回滚不会退还已发生的调用费用，也不会在服务之间复制会话状态。 [API 参考 →](/docs/api/compatible/openai) · [兼容指南 →](/docs/cloud/services/model/guides/openai-compatible) # 从 Anthropic 迁移 保留 Anthropic SDK 和 Messages 请求结构，修改地址、Key、模型 ID，再用新模型验证原提示词。 ```diff client = Anthropic( - base_url="https://api.anthropic.com", - api_key=os.environ["ANTHROPIC_API_KEY"], + base_url="https://api.deepraxis.com/anthropic", + api_key=os.environ["PRAXIS_API_KEY"], ) -model = "claude-sonnet-4-5" +model = "deepseek-flash" ``` ## 1. 准备 [#1-准备] 需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。 ```bash test -n "${PRAXIS_API_KEY:-}" ``` 期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。 ## 2. 选择模型 [#2-选择模型] | 原选择 | Praxis 选择 | 要检查什么 | | ---------------------------------- | ---------------------------------------- | ----------------------------------------- | | 官方 Claude ID，如 `claude-sonnet-4-5` | 本例使用 `deepseek-flash` | 这是另一个模型，不是 Claude 别名；重新评估质量与工具行为 | | 必须使用 Claude | 从 `/anthropic/v1/models` 复制可用的 Claude ID | 2026-10-12 目录包含 `claude-opus-5`；使用前确认所需能力 | SDK 基础地址只到 `/anthropic`，不要加 `/v1`，SDK 会追加 `/v1/messages`。目录仅列可走 Anthropic 协议的模型，与 `/openai/v1/models`、`/google/v1beta/models` 各自独立。 期望：完整模型 ID 出现在 `client.models.list()`；不要未经检查直接沿用官方 ID。 ## 行为差异 [#行为差异] * `thinking` 可用 `enabled`、`adaptive`、`disabled`，并支持 `output_config.effort`。部分模型不能关闭思考，返回 `400`（`cannot disable thinking`）；组合选项前查 [Messages 字段支持](/docs/api/compatible/anthropic/createMessage)。 * 从 `content` 中读取文本块，不要假定第一块就是正文；推理模型可能先返回思考块。 * `count_tokens` 返回带 `x-praxis-token-count: estimated` 的校准估算，不是精确计费依据，见 [统计 token](/docs/api/compatible/anthropic/countTokens)。 * Chat 的 `usage.cost` 是实付金额；Responses 和 Messages 目前不返回该字段。收到 `X-Praxis-Generation-Id` 时，可按 [生成记录 API](/docs/api/native/model/getGeneration) 用 `GET /model/v1/generation?id=生成ID` 查费用（记录可能延迟几秒）。若响应没有该头，去[控制台 → 用量与费用](https://console.deepraxis.ai/usage)查本次调用；不要把响应正文的 `id` 或 `X-Request-Id` 当成生成 ID，也不要将缺失费用当成零。 ## 不支持的操作与替代 [#不支持的操作与替代] 模型兼容接口提供 Messages、token 统计、模型列表和文件操作，各自限制见 [Anthropic API 参考](/docs/api/compatible/anthropic)。不提供 Message Batches（`/anthropic/v1/messages/batches`）；改为应用控制并发逐次调用 Messages，或保留原服务的批处理。官方模型 ID、文件 ID 不会自动映射；应选择目录模型，并重新上传需要的源文件。 ## 3. 验证一次请求 [#3-验证一次请求] ```bash unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy uv run -q --no-project --with openai --with anthropic python - <<'PY' import os from anthropic import Anthropic client = Anthropic( base_url="https://api.deepraxis.com/anthropic", api_key=os.environ["PRAXIS_API_KEY"], timeout=90.0, max_retries=0, ) models = client.models.list() assert "deepseek-flash" in {m.id for m in models.data} raw = client.messages.with_raw_response.create( model="deepseek-flash", max_tokens=1024, messages=[{"role": "user", "content": "Reply OK."}], ) reply = raw.parse() text = "".join(block.text for block in reply.content if block.type == "text") print("HTTP", raw.status_code) print("X-Request-Id:", raw.headers.get("x-request-id")) print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id")) print(text) assert raw.status_code == 200 and text and text.strip() assert raw.headers.get("x-request-id") PY ``` 期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。 ## 失败分支 [#失败分支] | 实测报错 | 处理 | | ------------------------------------------------ | ----------------------------- | | `400`（`cannot disable thinking`） | 移除关闭思考的要求，或选择目录声明可关闭思考的模型 | | `404`（`anthropic.messages is not offered for …`） | 选择 Anthropic 协议目录内且支持所需操作的 ID | | Message Batches 返回 `404 Not Found` | 逐次调用 Messages，或保留原批处理服务 | ## 4. 回滚 [#4-回滚] 恢复 `https://api.anthropic.com`、`ANTHROPIC_API_KEY` 中的原 Key 和原 Claude 模型 ID，同时恢复原思考选项与文件引用。重启客户端，运行原 Messages 冒烟请求，保留请求 ID。 期望：原服务返回可用正文。修改配置不会搬运文件、历史会话状态，也不会撤销已产生的费用。 [API 参考 →](/docs/api/compatible/anthropic) · [兼容指南 →](/docs/cloud/services/model/guides/anthropic-compatible) # 从 OpenRouter 迁移 保留 OpenAI SDK，替换连接配置与模型 ID；切流量前逐项处理 OpenRouter 专有选项。 ```diff client = OpenAI( - base_url="https://openrouter.ai/api/v1", - api_key=os.environ["OPENROUTER_API_KEY"], + base_url="https://api.deepraxis.com/openai/v1", + api_key=os.environ["PRAXIS_API_KEY"], ) -model = "openai/gpt-4o" +model = "deepseek-flash" ``` ## 1. 准备 [#1-准备] 需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。 ```bash test -n "${PRAXIS_API_KEY:-}" ``` 期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。 ## 2. 替换模型 ID [#2-替换模型-id] | OpenRouter 选择 | Praxis 选择 | | ----------------- | ----------------------------------- | | `openai/gpt-4o` | 先用 `deepseek-flash` 跑通；这是另一个模型，不是别名 | | `vendor/model` | 从 Praxis 目录复制完整 ID，不能假设去掉前缀就可用 | | 带 `:nitro` 后缀的 ID | 选不带后缀的目录 ID；不支持该后缀 | | `openrouter/auto` | 明确选择一个模型，或配置 `models` 回退列表 | 期望：`client.models.list()` 包含选定 ID。回退列表中的每个 ID 都必须是有效的 Praxis ID，并支持你调用的操作。 ## 行为差异 [#行为差异] | OpenRouter 选项 | 迁移处理 | | -------------------------------------------------- | --------------------------------------------------------------------- | | `provider.order`、`provider.only`、`provider.ignore` | 仅自带上游 Key（BYOK）可用；使用平台凭据时移除，否则返回 `400 provider_selection_not_allowed` | | `provider.allow_fallbacks`、`provider.sort` | 无效果；移除并重新评估选路假设 | | `provider.data_collection`、`provider.zdr` | 无效果；请求被接受不代表这些策略已执行 | | `models` | 支持模型回退列表；替换每个 ID 并检查响应中的 `model` | | `provider.require_parameters: true` | 对工具参数与已声明的采样参数进行支持检查；要求未声明支持的参数时返回 400；不支持的采样参数默认忽略 | 参数检查范围是工具参数与已声明的采样参数，不是供应商任意功能。准确范围见 [Chat Completions 字段支持](/docs/api/compatible/openai/createChatCompletion)。如果应用依赖被忽略选项所控制的数据策略，应继续使用原服务，直到单独确认所需策略。 Chat 的 `usage.cost` 是实付金额；Responses 和 Messages 目前不返回该字段。收到 `X-Praxis-Generation-Id` 时，可按 [生成记录 API](/docs/api/native/model/getGeneration) 用 `GET /model/v1/generation?id=生成ID` 查费用（记录可能延迟几秒）。若响应没有该头，去[控制台 → 用量与费用](https://console.deepraxis.ai/usage)查本次调用；不要把响应正文的 `id` 或 `X-Request-Id` 当成生成 ID，也不要将缺失费用当成零。 ## 不支持的操作与替代 [#不支持的操作与替代] `vendor/model`、`:nitro`、`openrouter/auto` 都不是受支持的模型选择方式，也不会自动映射。缺失的 OpenAI 端点见[不支持清单与替代](/docs/cookbook/migration/from-openai#不支持的端点与替代)。具体操作与字段以 [API 参考](/docs/api/compatible/openai) 为准，不要假设 OpenRouter 扩展也适用于 Responses。 ## 3. 验证一次请求 [#3-验证一次请求] 先跑通不带供应商偏好的最小 Chat 请求： ```bash unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy uv run -q --no-project --with openai --with anthropic python - <<'PY' import os from openai import OpenAI client = OpenAI( base_url="https://api.deepraxis.com/openai/v1", api_key=os.environ["PRAXIS_API_KEY"], timeout=90.0, max_retries=0, ) models = client.models.list() assert "deepseek-flash" in {m.id for m in models.data} raw = client.chat.completions.with_raw_response.create( model="deepseek-flash", messages=[{"role": "user", "content": "Reply OK."}], max_tokens=1024, ) reply = raw.parse() text = reply.choices[0].message.content print("HTTP", raw.status_code) print("X-Request-Id:", raw.headers.get("x-request-id")) print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id")) print(text) assert raw.status_code == 200 and text and text.strip() assert raw.headers.get("x-request-id") PY ``` 期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。 然后逐个加回应用需要的选项。期望：每次请求成功且返回预期模型；被忽略的字段不能作为策略生效的证据。 ## 失败分支 [#失败分支] | 实测报错 | 处理 | | ------------------------------------ | --------------------------- | | `400 provider_selection_not_allowed` | 平台凭据移除供应商选择；或先配置 BYOK 再选择上游 | | `404`，包含 `does not exist` | 将带厂商前缀、后缀或自动选择器的 ID 换成目录 ID | | `404 model_protocol_not_offered` | 选择提供该操作的模型 | ## 4. 回滚 [#4-回滚] 恢复 `https://openrouter.ai/api/v1`、原 `OPENROUTER_API_KEY`、原模型 ID 和保存的 OpenRouter 选项。重启客户端后跑原冒烟请求。不要把 Praxis Key 发给 OpenRouter。 期望：原请求返回可用正文与预期模型。Praxis 上已产生的调用费用仍保留。 [API 参考 →](/docs/api/compatible/openai) · [Cookbook：OpenAI SDK →](/docs/cookbook/sdk/openai-sdk) # 从其他网关迁移 先迁移一次请求：改 API 地址、Key 和模型 ID。下面示例面向兼容 OpenAI Chat Completions 的客户端，不会自动把其他请求协议转换成 Chat。 ## 1. 准备终端 [#1-准备终端] 准备 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。将 [Praxis 云 API Key](/docs/cloud/account/api-keys) 放入环境变量 `PRAXIS_API_KEY`，不要写入代码或日志。 ```bash test -n "$PRAXIS_API_KEY" ``` 期望：退出码为 0。退出码 1 表示变量未设置，先设置再继续。示例默认使用 `https://api.deepraxis.com`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。 ## 2. 修改三项配置 [#2-修改三项配置] 1. 将 `base_url` 改为 `https://api.deepraxis.com/openai/v1`。期望：地址只含一次 `/openai/v1`，不是控制台网址，也不是完整的 `/chat/completions` 端点。 2. 将客户端 Key 改为 `PRAXIS_API_KEY`。期望：不再向 Praxis 发送旧网关的 Key；另存原配置以便回滚。 3. 本次冒烟验证将模型 ID 改为 `deepseek-flash`。期望：它出现在 `GET /openai/v1/models?api=chat`。旧网关的供应商前缀或别名不一定在此有效。 按当前使用的 API 选择更详细的迁移指南： | 当前 API 或网关 | 指南 | | ----------------------------------- | ----------------------------------------------------------- | | OpenAI Chat Completions 或 Responses | [从 OpenAI 迁移](/docs/cookbook/migration/from-openai) | | OpenRouter | [从 OpenRouter 迁移](/docs/cookbook/migration/from-openrouter) | | Anthropic Messages | [从 Anthropic 迁移](/docs/cookbook/migration/from-anthropic) | ## 3. 验证新配置 [#3-验证新配置] 保存为 `gateway-migration.py`，运行 `uv run -q --no-project --with openai --with anthropic --with google-genai python gateway-migration.py`。 ```python import os from openai import OpenAI client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'], base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.com') + '/openai/v1') models = client.models.list(extra_query={'api': 'chat'}) print('catalog X-Request-Id:', models._request_id) assert 'deepseek-flash' in [model.id for model in models] response = client.chat.completions.create(model='deepseek-flash', messages=[{'role': 'user', 'content': 'Reply with exactly: MIGRATION_OK'}], reasoning_effort='none', max_tokens=256) print('X-Request-Id:', response._request_id) assert response.choices[0].finish_reason == 'stop' assert response.choices[0].message.content.strip() == 'MIGRATION_OK' assert response.usage is not None and response.usage.total_tokens > 0 print(response.choices[0].message.content) print('usage:', response.usage.model_dump()) ``` 期望：输出 `MIGRATION_OK`、大于 0 的 token 用量、目录请求 ID 与推理请求 ID，退出码 0。保留请求 ID 用于排障，不记录 Key。 ## 4. 切流量前检查 [#4-切流量前检查] 用自己的提示词检查流式、工具、结构化输出和[思考设置](/docs/cloud/services/model/guides/reasoning)。冒烟通过不代表模型行为相同。按需重建文件或响应资源：旧网关的 ID 不随配置迁移。验证失败时，一起恢复原地址、Key 和模型配置。 实测 `gpt-5.6-sol` 调用 Responses 返回 `model_protocol_not_offered`（HTTP 404）。支持 Chat 不代表支持 Responses，应按 [Responses 指南](/docs/cloud/services/model/guides/responses-api)查询对应目录。模型断言失败表示所选 ID 未出现在该协议目录中，应先核对再切流量。 [API 参考 →](/docs/api/compatible/openai) · [模型指南 →](/docs/cloud/services/model/guides/openai-compatible) # 实战场景 这里的每一篇都是一个完整的端到端场景：跨多个服务、用到多种能力、有可运行的结果。如果你只想接一个工具，去上面各分区；如果你想做一件事，从这里开始。 ## 已上线的场景 [#已上线的场景] | 场景 | 你将做成什么 | 涉及能力 | | -------------------------------------------------------------------- | --------------------------------- | ---- | | [给文档站加问答助手](/docs/cookbook/scenarios/docs-qa-assistant) | 按 ⌘K 弹出问答窗口，由服务型智能体回答帮助中心的问题 | 智能体 | | [在 SaaS 后台按登录用户嵌入](/docs/cookbook/scenarios/saas-embedded-assistant) | 按登录用户签发令牌，浮窗客服 + 侧栏助教，工具在服务端按用户鉴权 | 智能体 | ## 正在规划的场景 [#正在规划的场景] | 场景 | 你将做成什么 | 涉及能力 | | ------------ | ---------------------------------------- | --------- | | 构建一个 AI 客服 | 用 Agent SDK + 模型对话 + 上下文管理，搭建一个能回答问题的智能体 | 模型 · 智能体 | | 批量处理文档 | 用模型 + 文件上传 + 结构化输出，批量提取和转换文档内容 | 模型 · 文件 | | 搭建 RAG 问答 | 用嵌入 + 搜索 + 模型，让 AI 基于你的知识库回答问题 | 模型 · 搜索 | | 构建多 Agent 协作 | 用工作流 + 多智能体编排，让多个 AI 分工协作完成复杂任务 | 工作流 · 智能体 | 以上场景正在编写中，优先级由社区反馈驱动——你[想先看哪个](https://console.deepraxis.ai/support)，告诉我们就优先写。 # 给文档站加问答助手 本页带你给一个帮助中心或文档站加上「⌘K 问答」：访客按下 ⌘K（Windows / Linux 为 Ctrl+K）或点击搜索框，弹出一个居中的对话窗口，由服务型智能体依据你写好的内容回答。参照实现是仓库里「好物集」演示站（`apps/kit-demo`）的帮助中心页，路径 `/help`。 你需要：一个 Praxis API Key、一个能放后端接口的站点、一个前端页面。 ## 工作方式 [#工作方式] ```text 访客按 ⌘K ──▶ 页面加载 Kit，调用 getToken │ ▼ 你的后端 POST /api/praxis-token ──(API Key)──▶ POST /agent/v1/embed_tokens │ ◀── { token, expires_at } Kit（modal）──(token)──▶ Praxis API ──▶ 服务型智能体 ``` 浏览器里没有 API Key。Kit 只在访客第一次打开时才加载，之后令牌由 `getToken` 按需取得。 ## 1. 创建智能体并写入答案范围 [#1-创建智能体并写入答案范围] 1. 在 Console 打开「服务型智能体」，点「新建服务型智能体」。 2. 进入「接入与配置 · 配置 · 指令」，写明角色、回答范围和越界时怎么办，并把要回答的内容放进去。演示站的帮助中心智能体就是这样做的：把 FAQ 全文放进指令，要求「依据下面的内容回答，不编造政策、优惠或时效；范围外的问题请用户联系客服」，并且**不配置任何工具**。 3. 在「配置 · 安全」选择**运行环境**，在**来源白名单**里点「添加来源」，填你的站点来源（例如 `https://help.example.com`）。本地调试可打开「允许 localhost」。点「保存安全设置」。 4. 记下页面标题下方的智能体短号（旁边有复制按钮）。 期望：保存安全设置后出现「已保存，不产生新版本」；「接入与配置 · 试用调试」里能直接和智能体对话。 指令不是秘密，模型可能被用户要求复述，不要放不想公开的内容，见[传入上下文](/docs/cloud/services/agent/embed/context)。 ## 2. 后端签发令牌 [#2-后端签发令牌] 在 Console 的 API Keys 里创建一个专门用来签发令牌的 Key，放进后端环境变量。下面是一个与框架无关的处理函数，参照演示站的 `/api/praxis-token`： ```ts const API = "https://api-develop.deepraxis.com"; // 正式地址上线后替换 export async function handlePraxisToken(request: Request, currentUserId: string | null): Promise { if (!currentUserId) return Response.json({ error: "请先登录" }, { status: 401 }); const response = await fetch(`${API}/agent/v1/embed_tokens`, { method: "POST", headers: { Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`, // 占位：只放在后端 "Content-Type": "application/json", }, body: JSON.stringify({ agent: process.env.PRAXIS_AGENT, // 智能体 id 或短号 external_user_id: currentUserId, // 来自你的登录态，不接受前端传入 }), signal: AbortSignal.timeout(15_000), }); // 不要把上游错误原文转给浏览器 if (!response.ok) return Response.json({ error: "问答暂时不可用，请稍后重试" }, { status: 502 }); const { token, expires_at } = await response.json(); return Response.json({ token, expires_at }); } ``` 期望：已登录请求返回 HTTP 200 和 `{ token, expires_at }`；未登录返回 401。令牌字段与错误见[嵌入令牌与终端用户](/docs/cloud/services/agent/embed/tokens)。 ## 3. 前端：⌘K 打开 modal [#3-前端k-打开-modal] Kit 的 `layout: "modal"` 是居中的原生对话框，自带遮罩、焦点管理和 Esc 关闭。`launcher: { type: "none" }` 表示不显示启动按钮，由你的页面调用 `open()`。⌘K 快捷键由页面自己监听，Kit 不内置。 ```html ``` * `open()` / `close()` 是元素方法；窗口关闭时元素触发 `praxis.close` 事件，可以在里面把焦点还给搜索框。 * 想用 CDN 加载而不是自托管，见[安全](/docs/cloud/services/agent/embed/security)里的「子资源完整性」：浮动路径 `https://kit-develop.praxisusercontent.com/v1/praxis-kit.js`，或不可变路径 `/v0.1.0/praxis-kit.js` 配 `integrity`。 * 用 React 时换成 `@deepractice-ai/praxis-kit-react` 的 `` 与 `usePraxisAgent()`，`control.open()` 打开，见[嵌入方式](/docs/cloud/services/agent/embed/methods)。 期望：按 ⌘K 或点击按钮，弹出带遮罩的对话窗口并出现欢迎语与两个推荐问题；点推荐问题收到回复；按 Esc 关闭。 ## 4. 验证 [#4-验证] 不打开浏览器也可以验证后端和令牌： ```bash curl -X POST https://api-develop.deepraxis.com/agent/v1/embed_tokens \ -H "Authorization: Bearer $PRAXIS_API_KEY" -H "Content-Type: application/json" \ -d '{"agent":"<智能体 id 或短号>","external_user_id":"smoke-test"}' ``` 期望：HTTP 200，返回 `id`、`token`、`expires_at`。随后在 Console 的「运营与管理 · 签发记录」能看到这条记录，见[运营与管理](/docs/cloud/services/agent/embed/console-operate)。 ## 未登录的访客 [#未登录的访客] 演示站为了能让任何人试用，对帮助中心智能体在未登录时用固定的 `external_user_id: "guest"` 签发。这只适合演示：所有访客共用同一个终端用户身份，嵌入策略里「单个终端用户的活跃会话上限」「每分钟请求上限」按这个身份合计，封禁一个访客就等于封禁全部。正式站点请在「可公开 key」上线前只对已登录用户开放，或自行给每位访客分配稳定的匿名 ID。 ## 常见问题 [#常见问题] * **签发返回 `INVALID_PARAMS`「embed policy not configured」**：智能体还没有嵌入策略，回到「配置 · 安全」保存一次。 * **签发返回 `EMBED_USER_BLOCKED`**：这个 `external_user_id` 在封禁名单里，在「运营与管理 · 终端用户」解封。 * **弹窗打开但无法对话**：确认页面来源在来源白名单里，`api.url` 与签发令牌用的是同一个环境。 * **页面设置了 CSP 后脚本被拦截**：见[安全](/docs/cloud/services/agent/embed/security)里的内容安全策略。 下一步：[在 SaaS 后台按登录用户嵌入](/docs/cookbook/scenarios/saas-embedded-assistant) · [组件参考](/docs/cloud/services/agent/embed/component-reference) · [限制与错误](/docs/cloud/services/agent/embed/limits-and-errors) # 在 SaaS 后台按登录用户嵌入 本页带你把服务型智能体放进一个有登录的 SaaS 后台，并做到三件事：智能体知道**当前是谁**、知道**他正在看什么**、只能查**他自己的**数据。参照实现是仓库里「好物集」演示站（`apps/kit-demo`）的两个场景：右下角浮窗客服，和课程页右侧的课程助教。 你需要：一个 Praxis API Key、一个有登录态的后端、一个前端页面，以及（想让智能体查订单时）一个你自己的 MCP 服务。 ## 工作方式 [#工作方式] ```text 登录用户 ──▶ 你的后端 /api/praxis-token │ 用登录态里的用户 ID + 用户信息 ▼ POST /agent/v1/embed_tokens { agent, external_user_id, system_message } │ ◀── { token, expires_at } 浏览器（Kit）──(token)──▶ Praxis API ──▶ 智能体 ──MCP──▶ 你的订单服务 └ 带 X-Praxis-External-User-Id ``` 三类信息各走各的渠道，可信度不同，完整说明见[传入上下文](/docs/cloud/services/agent/embed/context)： | 信息 | 渠道 | 可信 | | ------------- | ----------------------- | ---------- | | 当前用户的姓名、会员等级 | 签发令牌时的 `system_message` | 是，来自你的后端 | | 用户正在看哪一课、播到哪里 | 页面上下文与前端工具 | 否，来自浏览器 | | 用户的订单 | 智能体调用你的 MCP 工具 | 取决于你的服务端鉴权 | ## 1. 创建智能体 [#1-创建智能体] 在 Console「服务型智能体」点「新建服务型智能体」，然后在「接入与配置 · 配置」里： 1. **指令**：写角色与边界。演示站客服的要点是：只回答本店商品、订单、退货与会员问题；查订单和退货必须使用订单工具，不编造订单；退货前先用一句话向用户确认订单与原因。 2. **MCP 与凭据**：添加 MCP 服务器，名称填 `orders`，类型选 HTTP，URL 填 `https://你的域名/mcp`。再到下方「凭据库」勾选存放该服务访问令牌的凭据库，并保存凭据库选择。凭据的「允许的主机」要包含 MCP 服务的域名，会话按它自动匹配凭据。 3. **工具与授权**：在「授权方式」里，查询类工具选「自动执行」，申请退货这类写入工具选「每次询问」。 4. **安全**：选运行环境，在来源白名单添加你的后台域名，保存安全设置。要允许用 `system_message` 之外的方式覆盖指令才打开「允许宿主覆盖指令」，这里不需要。 期望：在「试用调试」里用「模拟」页签填入 `external_user_id` 与 `system_message`，点「重新签发」后能和智能体对话，「上下文」页签的 host\_context 显示你填的内容。 ## 2. 后端：按登录用户签发，并带上用户信息 [#2-后端按登录用户签发并带上用户信息] ```ts const API = "https://api-develop.deepraxis.com"; // 正式地址上线后替换 export async function handlePraxisToken(request: Request, user: { id: string; name: string; level: string } | null) { if (!user) return Response.json({ error: "请先登录" }, { status: 401 }); const response = await fetch(`${API}/agent/v1/embed_tokens`, { method: "POST", headers: { Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ agent: process.env.PRAXIS_AGENT_SUPPORT, external_user_id: user.id, // 稳定且唯一，来自登录态 system_message: [{ type: "text", text: `当前用户 ${user.name}，会员等级 ${user.level}` }], }), signal: AbortSignal.timeout(15_000), }); if (!response.ok) return Response.json({ error: "客服暂时不可用，请稍后重试" }, { status: 502 }); const { token, expires_at } = await response.json(); return Response.json({ token, expires_at }); } ``` * `external_user_id` 只能来自你的登录态，不接受请求体里的值；它还是下面 MCP 鉴权用的身份。 * `system_message` 是文本块数组，合计不超过 8192 字节。它**不是秘密**，模型可能被要求复述。 * 课程助教是另一个智能体：同一个接口，换 `agent`，`system_message` 里换成学员信息。演示站用一个 `agent` 参数在后端选择，并且只接受预先登记的几个值。 期望：HTTP 200 与 `{ token, expires_at }`；未登录 401。 ## 3. 前端：浮窗客服 [#3-前端浮窗客服] ```js import "/praxis-kit.js"; // Kit 的构建产物，由你的站点提供 const agent = document.createElement("praxis-agent"); agent.setOptions({ api: { url: "https://api-develop.deepraxis.com", getToken: async () => { const response = await fetch("/api/praxis-token", { method: "POST", credentials: "same-origin" }); if (!response.ok) throw new Error("客服暂时不可用，请稍后重试"); return (await response.json()).token; }, }, agent: { name: "好物集客服" }, layout: "popup", launcher: { type: "bubble", position: "bottom-right", label: "咨询客服" }, header: { title: "好物集客服", subtitle: "通常几秒内回复" }, startScreen: { greeting: "你好！有问题随时问我。", prompts: ["我的订单到哪了", "怎么退货"].map(text => ({ label: text, prompt: text })), }, }); document.body.appendChild(agent); ``` 只在用户登录之后才创建这个元素；退出登录时整页刷新，这样上一位用户的令牌不会留在内存里。 期望：右下角出现气泡，点开出现欢迎语；问「我的订单到哪了」时智能体调用订单工具并给出该用户的订单。 ## 4. 前端：侧栏课程助教，带页面上下文和前端工具 [#4-前端侧栏课程助教带页面上下文和前端工具] 课程页用 `layout: "sidebar"`（右侧 400px 非模态面板，需要你为它在页面上留出位置）。助教要知道「学员正在看哪一课、播到哪里」，用两个入口：页面上下文放每轮都用得上的小事实，前端工具放需要时才读的数据。 先在智能体定义的 `tools` 里声明前端工具（类型 `custom`，写法见[前端工具与页面上下文](/docs/cloud/services/agent/embed/client-tools)）： ```json { "type": "custom", "name": "get_playback_progress", "description": "读取学员当前的视频播放进度", "input_schema": { "type": "object", "properties": {}, "additionalProperties": false } } ``` 再在页面里实现： ```js const tutor = document.createElement("praxis-agent"); tutor.setOptions({ api: { url: "https://api-develop.deepraxis.com", getToken: fetchTokenForTutor }, agent: { name: "课程助教" }, layout: "sidebar", launcher: { type: "none" }, header: { title: "课程助教", icon: "message-circle" }, }); // 页面上下文：随每条用户消息附带，标记为不可信 tutor.setReadable("course", "降噪耳机入门"); tutor.setReadable("lesson", "第 1 课：认识主动降噪"); // 前端工具：智能体调用时在页面里执行，返回值交还给智能体 tutor.onClientTool = ({ name }) => { if (name !== "get_playback_progress") throw new Error("unknown tool"); return { lesson: "第 1 课：认识主动降噪", position_seconds: 83, duration_seconds: 300, playing: true }; }; document.body.appendChild(tutor); tutor.addEventListener("praxis.open", () => document.body.classList.add("tutor-open")); tutor.addEventListener("praxis.close", () => document.body.classList.remove("tutor-open")); document.querySelector("#open-tutor").addEventListener("click", () => tutor.open()); ``` 换课时再调用一次 `setReadable("lesson", …)`，之后每条消息自动带最新值。`onClientTool` 是元素的 JavaScript 属性，不是 `setOptions` 的选项；对不认识的工具名必须抛错。限制、超时与 React 写法见[前端工具与页面上下文](/docs/cloud/services/agent/embed/client-tools)。 期望：打开侧栏后问「我现在看到哪了」，智能体调用 `get_playback_progress` 并据返回值回答，页面上能看到它没有编造进度。 ## 5. 服务端按用户鉴权的 MCP 工具 [#5-服务端按用户鉴权的-mcp-工具] 平台调用你的 MCP 服务时会带上 `X-Praxis-External-User-Id`（令牌里的 `external_user_id`）、`X-Praxis-Agent-Id`、`X-Praxis-Session-Id`。工具**必须**按这个头限定数据范围，不要用模型传来的参数确定用户。 ```ts // MCP 请求入口：先校验平台出示的访问令牌，再取用户身份 export async function handleMcp(request: Request, expectedToken: string) { if (request.headers.get("authorization") !== `Bearer ${expectedToken}`) { return Response.json({ error: "未授权" }, { status: 401 }); } const userId = request.headers.get("X-Praxis-External-User-Id"); // 每个请求单独读取 // list_orders: 只返回 userId 名下的订单 // request_return: 先确认订单属于 userId，再受理 // userId 缺失或不认识 → 以工具错误返回，不返回任何数据 } ``` 演示站的 MCP 服务有两个工具：`list_orders`（`readOnlyHint: true`）和 `request_return`（`destructiveHint: true`，参数 `order_id`、`reason`，订单不属于当前用户时返回「订单不存在或不属于当前用户」）。每个请求单独创建服务与闭包，并发请求之间不会串用户。 期望：用 alice 登录问订单只看到 alice 的订单；换 bob 登录看到 bob 的；让智能体「查 alice 的订单」时 bob 拿不到任何数据。询问确认只是帮用户确认意图，不是安全手段，详见[工具授权](/docs/cloud/services/agent/embed/tool-authorization)。 ## 常见问题 [#常见问题] * **智能体说查不了订单**：在「配置 · MCP 与凭据」确认 MCP 服务器地址可访问，凭据库已勾选，且凭据的允许主机包含该域名。 * **工具总是返回「缺少用户身份」**：只有会话属于某位终端用户时才带身份头；确认令牌签发时传了 `external_user_id`。 * **侧栏遮住了页面内容**：侧栏是浮在页面上的面板，要用 `praxis.open` / `praxis.close` 事件给页面留出空位。 * **前端工具总是「not available」**：`onClientTool` 要在智能体调用之前赋到元素上。 下一步：[给文档站加问答助手](/docs/cookbook/scenarios/docs-qa-assistant) · [令牌与终端用户](/docs/cloud/services/agent/embed/tokens) · [安全](/docs/cloud/services/agent/embed/security) 导出自 Praxis 文档 · 2026-10-20 · 共 42 页