---
title: AI 助手
description: 配置云端、兼容 API 或本地 CLI 模型，在 Schema 上下文中生成 SQL、分析数据并执行受控 Agent 工作流。
---
AI 助手把当前数据库、Schema、SQL、错误、结果预览和用户点名的对象组合成上下文，用于生成 SQL、解释查询、优化语句、修复错误和分析数据。
Ask 模式只生成建议；Agent 模式在用户明确要求真实数据时可以调用查询工具。任何模型输出都可能错误。执行 SQL 前仍应检查目标连接、字段、过滤条件、参数和影响范围。
## 支持的模型接入方式
### API 供应商
DBX 内置以下配置预设：
- Claude
- OpenAI
- Gemini
- DeepSeek
- Qwen
- MiniMax
- Ollama
- OpenAI Compatible
- Anthropic Compatible
- Custom
兼容或自定义配置可以设置端点、模型、API 风格、认证方式、代理、上下文窗口和额外 HTTP 请求头。API 风格包括 OpenAI 风格 completions、Responses API 和 Anthropic Messages。供应商支持时，DBX 会读取模型列表并过滤掉不适合对话/Agent 的模型。
### 本地 CLI Agent
Desktop 还可以直接调用已安装并登录的：
- Claude Code CLI
- Codex CLI
- Pi Coding Agent
可以配置可执行文件路径和额外环境变量。CLI Agent 运行在 Desktop 所在电脑，并通过 DBX 提供的受限 MCP 工具访问当前数据库。Docker/Web 不会显示这些本机 CLI 供应商，因为服务器不能假设浏览器电脑上安装了对应命令。
## 添加配置
### 打开 AI 设置
在编辑器设置中进入 AI，添加一个命名配置。可以为同一供应商保存多套端点或凭据。
### 选择供应商和模型
使用预设、兼容 API、自定义端点或本地 CLI。模型列表可发现时从供应商或本地 CLI 读取，也可以手动填写。手动填写的模型会保存到当前配置；当兼容供应商未提供模型发现接口或发现失败时，已保存的模型仍可选择。
### 配置认证和推理参数
API 模式填写 API Key、认证方式、端点、代理和自定义 HTTP 请求头。请求头可用于网关认证或租户路由，例如 `X-GoModel-User-Path: /dbx-assistant`；模型发现、连接测试、对话和 Agent 请求都会携带它们。支持的模型可以选择 effort、reasoning 或 thinking；具体选项来自供应商能力，而不是对所有模型统一显示。
### 测试并保存
测试会报告成功、延迟、实际模型和认证、限流、超时、模型不存在等错误类别。
API Key、自定义请求头的值、CLI 环境变量和自定义端点可能具有敏感性。不要把设置截图、导出的配置或调试日志发送到不可信位置。
## Ask 和 Agent
| 模式 | 适合任务 | 工具和执行行为 |
| --- | --- | --- |
| Ask | 生成、解释、优化、修复、转换 SQL，或基于已有上下文给建议 | 不主动执行数据库查询；最终答案应明确区分建议和已验证结果 |
| Agent | “查出结果”“对比真实数据”“先看表结构再回答”等需要迭代取证的任务 | 可以列表、读字段、取样和执行只读查询；写入必须经过精确确认 |
Agent 只有在原始请求明确要求真实数据/结果时才应执行查询。仅要求“写一条 SQL”时，即使处于 Agent 模式，也应返回 SQL 而不是自动运行。
## Agent 轮次和重试
- **最大 Agent 轮次**：默认 30，可配置 5–500。它限制模型、工具调用和修复循环的总轮数，防止复杂任务无限运行
- **最大 API 重试次数**：默认 2，可配置 0–10。只用于限流、超时和临时网络错误；Claude Code、Codex 和 Pi CLI 不使用这个 API 重试设置
- 达到轮次上限、用户取消、连接失败或工具策略拒绝时，Agent 会停止并保留已有步骤和错误
提高轮次上限会增加时间、数据库读取次数和模型成本。应先通过明确提示、表提及和缩小任务范围减少无效探索。
## Schema、表和 SQL 文件上下文
AI 上下文可以包含：
- 数据库类型、连接名称、数据库和 Schema
- 当前编辑器 SQL、选中 SQL 和最近错误
- 表、字段、索引、外键和少量样例数据
- 当前结果集的有限预览
- 用户选择的提示模板
- 被提及的保存 SQL 文件内容
在输入框键入 `@` 可以搜索表和保存的 SQL 文件：
- `@users`：优先加入 `users` 的元数据
- `@public.orders`：指定 Schema 中的表
- 同时选择多张表或 SQL 文件：把相关上下文一起交给模型
完整 Schema 过大时会截断。表提及比让模型在所有对象中猜测更可靠，也能减少 token 和元数据请求。
## 全局指令和提示模板
设置中可以维护：
- **全局指令**：每次 AI 请求都注入，例如命名规范、时区、软删除字段和生产约束
- **提示模板**：按场景保存可复用规则，例如“只生成 PostgreSQL 兼容 SQL”或“分析必须包含索引建议”
助手中可以同时选择多个模板。DBX 在发送时冻结当前全局指令和模板快照，因此请求开始后修改设置不会改变已经运行的任务。
模板会进入模型上下文，应避免放入密码、令牌或不必要的业务数据。规则冲突时，模型未必能按预期选择优先级，应保持全局指令和模板简短、明确且互不矛盾。
## 写入和生产安全
AI Agent 的执行边界是后端强制的，不只是提示词：
1. 只读工具可以按任务调用
2. 非只读 SQL 必须先作为明确的 SQL 提案展示
3. 用户确认后，授权只绑定到同一连接、同一数据库和完全相同的 SQL 文本
4. 授权只对下一次运行有效，不会变成永久写入权限
5. 生产数据库上的写入和 DDL 不会授权给 AI Agent；模型只能返回 SQL 供用户在 DBX 中人工审阅执行
连接只读保护、生产保护和数据库账号权限仍是上限。即使用户确认，目标变化、SQL 变化、空确认或后端风险分类不通过都会使授权失效。
AI Agent 不会获得“以后都可以写”的授权，也不会绕过 MCP 策略、连接只读保护或数据库权限。更多边界见 [生产环境安全](/cn/docs/production-safety)。
## 推理强度和 Thinking
不同供应商使用不同机制：枚举 effort、reasoning level、布尔 thinking、整数预算或自定义文本。DBX 按当前模型能力展示可用选项，并记住每个配置/模型的选择。
- 简单生成或解释可使用供应商默认或较低强度
- 多表推理、复杂优化和错误诊断可提高强度
- 更高强度通常增加延迟和费用，但不保证答案正确
不要把 UI 中的统一标签理解为所有供应商拥有相同推理语义。
## 对话、历史和导出
- 输入框支持使用 ↑ / ↓ 浏览当前提示历史
- 对话可以按连接和数据库保存，便于继续上下文
- 每条最终 AI 分析可以导出为 Markdown，文件包含连接名、时间和最终回答
- Markdown 导出只包含最终分析内容，不会把内部 reasoning 或 Agent 步骤附加到文件中
导出内容仍可能包含表名、SQL、结果片段和业务数据，分享前请审阅和脱敏。
## 常见任务
### 生成 SQL
> 根据 `@orders` 和 `@customers` 生成最近 30 天客户销售额 Top 10 查询，只返回 SQL，不执行。
明确写出“不执行”可以让意图更清晰。检查时间函数、Schema 限定、JOIN 键、空值和返回行数。
### 分析真实数据
> 查询 `@orders` 最近 7 天每天的订单数，执行只读查询并解释异常峰值。
这类请求适合 Agent 模式，因为它明确要求真实结果。
### 修复错误
把失败 SQL、数据库错误和涉及的表一起提供。AI 可以读取字段和方言信息，但版本特有行为、权限、锁和运行计划仍需人工验证。
## 隐私和故障排查
- 云端供应商会收到发送给模型的提示、Schema 摘要、SQL 和有限结果上下文；以供应商隐私条款为准
- Ollama 和本地 CLI 可以在本机运行，但模型进程和 CLI 插件仍可能有自己的联网或日志行为
- 代理、兼容端点和自定义网关可能记录请求内容
- 测试失败时先检查端点、认证方式、模型名、代理和模型是否支持当前 API 风格
- Agent 反复失败时减少上下文、点名目标表、降低任务范围，并查看具体工具错误，而不是只提高轮次上限
## 相关功能
查看 AI、MCP、只读连接和生产保护的统一边界。
让外部 AI 编程助手通过 DBX 访问数据库。
了解 AI 所使用的当前 SQL、结果和元数据上下文。