# 频道 Source: https://docs.asktable.com/concepts/agent/channel 频道把智能体接入飞书、Slack 等外部 IM，让用户无需登录 AskTable，直接在 IM 里对话问数。本页介绍频道的作用、配置要素和连接状态。 ## 什么是频道 频道是把[智能体](/concepts/agent/overview)接到外部 IM 的通道。配置好频道后，用户不必登录 AskTable，直接在 IM 里就能和智能体对话问数。目前支持**飞书**和 **Slack**。 ## 频道能做什么 把一个智能体绑定到 IM 后： * 用户在 IM 里 @ 或私聊机器人，就能用自然语言问数 * 智能体的回答直接发回 IM 这是双向的：消息进得来，结果回得去。适合把数据分析能力直接送到团队日常沟通的地方。 ## 配置要素 一个频道包含： | 要素 | 说明 | | ---------- | --------------------------------------------------------------------------------------------------------- | | **生效平台** | 智能体详情页「频道」下拉三选一：不启用 / 飞书 / Slack。切换非破坏——另一平台的凭证配置保留，切回即复用；选「不启用」即停用（配置留存） | | **凭证** | 飞书为 App ID、App Secret，以及可选的 Encrypt Key、Verification Token；Slack 为 Bot Token（`xoxb-`）与 App Token（`xapp-`） | | **在话题中回复** | 回答是开话题还是直接发在群里。飞书默认关，Slack 默认开 | | **深度推理** | 开启后模型推理更长时间，适合复杂问题 | | **渠道偏好** | 最多 1024 字的常驻要求，例如「先给结论」 | ## 连接状态 频道创建后会显示实时连接状态： | 状态 | 含义 | | ------- | --------------------------- | | **未连接** | 尚未与 IM 建立连接 | | **连接中** | 正在建立连接 | | **已连接** | 当前凭证校验通过，且 WebSocket 长连接仍存活 | | **错误** | 平台拒绝连接或连接异常；界面会显示脱敏后的错误摘要 | 状态每 5 秒自动刷新。手动点「刷新」只会立即重新读取状态，不会发起重连；断线重连由飞书或 Slack SDK 自动完成。绿点只说明平台长连接可用，不保证 Agent 的权限、任务执行和回复投递一定成功。 ## 最近消息 频道卡片只保留最近一条入站消息。主界面用 **接收消息 → 处理中 → 已回复** 这条进度表示当前阶段，不再把处理和回复拆成两条状态。 点击「详情」可以查看底层处理状态、回复状态、消息所在空间、消息 ID、接收时间和更新时间。旧消息即使稍后完成，也不会覆盖更新的消息。界面中的错误仅为最多 200 字的安全摘要，不包含 token、堆栈或平台原始响应。 ## 配置步骤 在 IM 侧创建应用、获取凭证、配置权限的完整步骤，见指南： * [接入飞书](/how-to/connect-feishu) * [飞书权限配置](/how-to/feishu-permissions) ## 常见问题 **Q: 一个智能体可以有多个频道吗？** A: 可以。一个智能体可同时接飞书和 Slack；但一个频道只对应一个智能体。 **Q: 谁能在 IM 里使用？** A: 默认所有人可用。若当前渠道开启了白名单（每个渠道独立开关），仅白名单内且在该渠道有身份绑定的成员可用，详见 [智能体](/concepts/agent/overview) 的权限说明。 **Q: 群里提问一定要 @ 机器人吗？** A: 是。两个平台都只提供「读 @ 我的」和「读整个频道」两档权限，我们刻意不要后者——机器人因此只能看到 @ 了自己的消息。飞书开了「在话题中回复」后，话题内追问仍需 @。 **Q: 显示已连接，但消息没有回复怎么办？** A: 「已连接」只验证平台长连接。请继续看「最近消息」：没有记录通常表示事件订阅、应用权限或机器人未进群；点击「详情」后，处理失败表示 Agent 任务异常，回复失败表示平台投递异常。 # 嵌入 Source: https://docs.asktable.com/concepts/agent/embed 嵌入让你把智能体以 iframe 放进自己的网站，访客无需登录即可直接问数。本页介绍嵌入的作用、配置步骤、访客体验与安全模型。 ## 什么是嵌入 嵌入把[智能体](/concepts/agent/overview)以 ` ``` ## 访客体验 访客打开嵌入页后： * 无需登录，也不用选数据源或角色，直接在输入框提问 * 只能在地址绑定的角色数据范围内得到回答 * 可在**快速 / 深度思考**之间切换（初始为快速，响应更即时） * 24 小时内刷新页面会**接着同一个对话**；超过则自动开始新对话，也可随时点【新对话】重新开始 ## 安全模型 嵌入面向匿名公网访客，安全靠这几层： * **固定角色数据范围** — 访客只能问到绑定角色允许的数据；改角色只影响之后新建的对话 * **不可猜的地址 ID** — 地址 ID 是随机串（`emb_` 前缀），不暴露枚举 * **可信域名白名单** — 打开【可信域名】后，只有白名单域名的页面能嵌入 * **禁用即停** — 停用地址后，正在进行的会话立即断开 嵌入是公开入口。绑定角色时，请确认该角色的数据范围适合对外公开。 ## 嵌入 vs 频道 两者都让**外部用户**用智能体，但形态不同： * **频道**：接入飞书等 IM，用户在 IM 里对话 * **嵌入**：以 iframe 放进你的网站，面向**匿名网页访客**，绑定一个固定角色，所有人看到相同的数据范围 ## 常见问题 **Q: 访客需要登录吗？** A: 不需要。嵌入面向匿名访客，打开页面即可提问。 **Q: 不同访客看到的数据一样吗？** A: 一样。一个地址绑定一个固定角色和固定角色变量，所有访客都在这个范围内。要按访客身份隔离数据，用频道 + 权限，而不是嵌入。 **Q: 怎么限制只有我的网站能嵌入？** A: 打开【可信域名】开关，把你的域名加入白名单。默认不限制来源。 **Q: 停用地址后正在聊天的访客会怎样？** A: 会话立即断开。重新启用后，访客刷新页面即可重新开始。 # 智能体 Source: https://docs.asktable.com/concepts/agent/overview 智能体是 AskTable 的核心单元——配好数据源与技能，它就能用自然语言回答数据问题。本页讲清智能体的组成，以及它与技能、频道、定时任务的关系。 ## 什么是智能体 智能体（数据智能体）是你在 AskTable 里配置的虚拟数据分析助手。给它接上数据源、挂上技能，它就能用自然语言回答数据问题——理解你的提问、查询数据、给出结论。 智能体是你与数据对话的核心单元。后面要讲的**技能**、**频道**、**定时任务**，都是围绕智能体展开的。 ## 智能体能做什么 * 理解自然语言提问，自动定位相关的表和字段 * 生成并执行 SQL 查询数据 * 运行 Python 做复杂计算和数据处理 * 把结果画成图表 * 提问不清楚时，主动向你追问澄清 * 联网搜索公开数据（需开启） 具体开启哪些能力，由智能体的【能力】配置决定，见下。 ## 智能体的组成 | 组成 | 说明 | | ------- | ----------------------------------------------------------------- | | **数据源** | 智能体能访问哪些数据库、数据表。不接数据源就无数据可查。 | | **技能** | 可复用的分析方法，教智能体怎么分析（如异常检测、对比分析）。详见 [技能](/concepts/agent/skill)。 | | **能力** | 一组开关：Python、图表、追问澄清、联网搜索。前三项默认开启，联网搜索默认关闭。 | | **权限** | 白名单开关按渠道独立配置（飞书 / Slack 各一个）。开启后，仅白名单内成员可通过该渠道使用智能体，并可按角色做行级数据隔离。 | | **头像** | 智能体的展示图标。 | ## 从模板创建 AskTable 内置 9 个智能体模板，每个模板预置了一组适配场景的技能，开箱即用，例如：门店经营分析师、电商数据盯盘助手、财务数据分析师、市场洞察分析师、用户增长分析师、高管数据助手等。 从模板创建时，会自动预填名称、描述和技能，你只需选上自己的数据源即可。也可以选择【空白】从零配置。模板本身只读，基于它创建出的智能体可以自由调整。 ## 与技能、频道、定时任务、嵌入的关系 围绕智能体有四个配套概念： 给智能体装上可复用的分析方法。 让用户从飞书等 IM 直接和智能体对话。 让智能体按计划自动跑分析并推送结果。 把智能体以 iframe 放进你自己的网站，供匿名访客问数。 一句话概括：**技能**决定智能体会什么，**频道**和**嵌入**决定用户从哪里找到它，**定时任务**让它自动干活。 ## 常见问题 **Q: 一个智能体可以接多个数据源吗？** A: 可以。智能体能访问你为它配置的全部数据源。 **Q: 不挂技能能用吗？** A: 能。技能是增强项。不挂技能时智能体仍能查数、画图、跑 Python，只是少了预置的分析方法。 **Q: 模板能直接改吗？** A: 模板是只读的起点。基于模板创建出自己的智能体后，名称、数据源、技能、能力都可以自由调整。 # 定时任务 Source: https://docs.asktable.com/concepts/agent/schedule 定时任务让智能体按计划自动运行分析，并把结论推送到飞书或邮件，适合周期性监控与报表。本页介绍配置要素、运行历史，以及它与频道的区别。 ## 什么是定时任务 定时任务让[智能体](/concepts/agent/overview)**按计划自动跑**一段分析，并把结论推送给你。你定好「跑哪个分析、多久跑一次、结果发到哪」，到点它就自己执行，不用人盯着。 ## 典型场景 * 每天早上 9 点，自动分析昨日订单关键指标，推送到飞书群 * 每周一汇总上周销售，发到指定邮箱 * 每月初生成经营月报 适合周期性的监控和报表。 ## 配置要素 | 要素 | 说明 | | -------- | ------------------------------------------------------------- | | **指令** | 要智能体做的分析，用自然语言描述，如「分析昨日订单并输出关键指标」 | | **频率** | 用 cron 表达式设定，如每天 `0 9 * * *`、每周一 `0 9 * * 1`。**间隔不得小于 10 分钟** | | **通知方式** | 结果送达的渠道：飞书 webhook 或邮件 | | **启用** | 开关；启用前必须先设好通知方式 | 每个定时任务都归属一个智能体，由它来执行分析。 ## 运行与历史 * **立即触发** — 不等到点，手动跑一次，验证配置是否正确 * **运行历史** — 每次执行都有记录，可查看结论、状态（成功 / 失败）和时间 * **下次触发** — 显示下一次自动执行的时间 ## 定时任务 vs 频道 两者都连接智能体，但方向不同： * **频道**：用户主动发起，双向对话——你问，它答 * **定时任务**：系统按计划发起，单向推送——到点自动跑，把结果送给你 ## 常见问题 **Q: 定时任务的结果发到哪？** A: 飞书 webhook（群机器人）或邮件，二选一。 **Q: 最短能多久跑一次？** A: 最小间隔 10 分钟。 **Q: 任务失败会怎样？** A: 运行历史里会记录失败状态和原因，方便排查（分析失败 / 推送失败）。 # 技能 Source: https://docs.asktable.com/concepts/agent/skill 技能是可复用的分析方法，挂到智能体上即可让它按既定套路分析数据。本页介绍内置技能、自定义技能，以及技能如何生效。 ## 什么是技能 技能是一份可复用的分析方法。它本质是一段写给智能体的指令，告诉它「遇到某类问题该怎么分析」。把技能挂到[智能体](/concepts/agent/overview)上，智能体在分析时就会照着这套方法做。 ## 为什么需要技能 同样一份数据，分析方法决定结论的深度。技能把专家的分析套路沉淀下来——比如「怎么判定异常」「怎么做归因」——一次定义，多个智能体复用，不必每次在对话里重复交代。 ## 内置技能 AskTable 预置了 11 个通用分析技能，开箱即用： | 技能 | 说明 | | ---------- | -------------------------- | | **异常检测** | 自动发现数据中的异常波动，识别超出正常范围的指标变化 | | **预测趋势** | 基于历史数据预测未来走势，提供趋势分析和预测区间 | | **压力测试** | 模拟不同假设场景，评估指标在极端条件下的表现 | | **下钻指标** | 从汇总指标逐层拆解，定位问题根源 | | **编排报告** | 自动生成结构化数据分析报告 | | **对比分析** | 多对象、多维度横向对比，发现差异和机会 | | **归因分析** | 分析指标变动的核心驱动因素，量化各因子贡献度 | | **指标解读** | 用业务语言解读数据，确保数据结论准确且易于理解 | | **数据质量检测** | 主动检测数据质量问题，确保分析结果可信 | | **业务语言生成** | 将数据分析结果转化为生动的业务叙述 | | **周期分析** | 识别数据中的周期模式，支持周期性波动分析 | ## 自定义技能 除内置技能外，你可以创建自己的技能。一个技能包含三部分： * **名称** — 技能的名字，如「门店巡检清单」 * **描述** — 一句话说明这个技能做什么 * **内容** — 写给智能体的具体指令（提示词），描述分析的步骤、口径和输出格式 内置技能只读，自定义技能可以随时编辑、删除。 ## 技能如何生效 技能不是独立运行的程序，而是**注入到智能体的系统提示里**。当你和挂了技能的智能体对话时，所有技能的内容会一起作为背景指令交给智能体，它据此选择合适的方法来分析。挂的技能越贴合场景，回答越专业。 ## 常见问题 **Q: 一个智能体能挂多个技能吗？** A: 可以。模板通常预置 3-6 个技能，你也可以按需增减。 **Q: 技能会自己执行查询吗？** A: 不会。技能只提供方法指引，真正查数、画图由智能体的能力（SQL、Python、图表）完成。 **Q: 内置技能能改吗？** A: 内置技能只读。需要定制时，新建一个自定义技能。 # 画卷 Source: https://docs.asktable.com/concepts/canvas 画卷是 AskTable 的 AI 可视化数据分析画布，用自然语言和节点化方式构建从数据获取到分析呈现的完整流程，让分析可视化、可复用、可协作。 ## 什么是画卷 画卷是 AskTable 的可视化数据分析画布。通过 AI 驱动的自然语言交互与节点化的方式，构建从数据获取到分析呈现的完整流程。 **核心价值：** 让数据分析流程可视化、可复用、可协作。 ## 为什么需要画卷 传统数据分析面临三个困境： 1. **流程不透明** - SQL 查询、数据处理、图表生成散落各处，难以追溯 2. **无法复用** - 每次分析都要重新编写代码，重复劳动 3. **协作困难** - 分析逻辑藏在代码里，团队成员难以理解和接手 画卷通过 AI 驱动的节点化设计解决这些问题： * 用自然语言描述需求，AI 自动创建对应的分析节点 * 节点间的依赖关系自动构建数据流转路径 * 整个画卷即完整的分析流程，可保存、分享、复用 ## 快速开始 ### 创建第一个画卷 1. 点击左侧导航栏"画卷" 2. 点击"创建画卷"按钮 3. 进入画卷后，在 Welcome 页面的聊天框中用自然语言描述你的分析需求，例如： * "查询本月销售数据并生成趋势图" * "导入这份 Excel 文件，分析各地区的销售额" * "搜索 2024 年中国 GDP 增长率" 4. AI（Autopilot）会自动理解你的意图，创建对应的节点并在画布上呈现 ## 节点类型 画卷支持五种节点类型： | 节点 | 说明 | 适用场景 | | ------------- | ----------------------- | ----------------- | | **数据节点** | 连接企业内部数据库，用自然语言查询和分析数据 | 业务数据分析、运营报表 | | **图表节点** | 将数据可视化为图表 | 趋势图、占比图、对比分析等 | | **Python 节点** | 编写自定义 Python 代码处理数据 | 复杂计算、数据清洗、自定义分析逻辑 | | **Excel 节点** | 导入 Excel / CSV 文件进行即时分析 | 临时数据分析、外部数据导入 | | **联网搜索节点** | 搜索公开市场数据、行业报告和趋势分析 | 市场研究、行业分析 | ## 画卷编辑器 ### 界面布局 * **顶部工具栏** — 画卷命名、保存 * **中央画布** — 节点编排区域，以 ReactFlow 图形方式展示节点及其依赖关系 * **右侧面板** — 节点详情（数据表 / 图表展示）+ 对话记录（与 AI 的交互历史） ### 节点创建方式 * **Welcome 聊天输入** — 空画卷时，直接在 Welcome 页面用自然语言描述需求，AI 自动创建节点 * **右键菜单** — 在画布空白处右键，选择"查询数据"、"联网搜索"或"导入 Excel" * **悬浮聊天输入** — 点击已有节点的聊天按钮，在悬浮输入框中描述需求，AI 会基于上下文创建新节点 * **文件拖拽** — 将 `.xlsx`、`.xls`、`.csv` 文件直接拖入画布，自动创建 Excel 节点 ### 节点操作 * **拖拽节点** — 在画布上移动节点调整布局 * **点击节点** — 在右侧面板查看数据结果、图表和对话历史 * **节点工具栏** — 每个节点提供快捷操作：创建图表、继续对话、创建 Python 节点、重新运行、删除 * **多选操作** — 选中多个数据/Python/Excel 节点后，可一键"继续追问"或"创建 Python 节点" ### 边的自动生成 节点之间的连线（边）由系统**根据数据依赖关系自动生成**，无需手动拖拽端口连接。当一个节点引用了另一个节点的数据时，系统会自动在两者之间绘制连线。 ## 使用场景 ### 场景一：周期性业务报表 用自然语言描述需求，AI 自动构建分析流程： 1. 输入"分析本月销售数据，计算同比环比，生成趋势图" 2. AI 创建数据节点查询数据、图表节点生成可视化 3. 下次使用时，重新运行画卷即可自动更新结果 ### 场景二：市场趋势分析 组合多个数据源： 1. 输入"搜索 2024 年行业报告，并与我们的业务数据对比" 2. AI 创建联网搜索节点获取行业数据、数据节点查询自有数据、图表节点对比展示 ### 场景三：临时数据探索 快速分析上传的文件： 1. 将 Excel 文件拖入画布 2. 在悬浮聊天框中输入"分析各区域销售额并生成柱状图" 3. AI 基于文件数据创建分析节点和图表 ## 与其他功能的关系 **画卷 vs 对话** * 对话：一次性问答，适合临时查询 * 画卷：可复用流程，适合周期性、多步骤分析 **画卷 vs 报告** * 报告：静态文档，展示分析结果 * 画卷：动态流程，可持续更新数据 **画卷 vs 速查** * 速查：快速查询单个指标 * 画卷：复杂分析流程，多步骤处理 ## 常见问题 **Q: 画卷可以重新运行吗？** A: 可以。点击节点工具栏的"重新运行"按钮，会重新执行该节点并更新结果。 **Q: 如何分享画卷给团队成员？** A: 画卷归属于项目，项目成员可根据权限查看和编辑画卷。 **Q: 画卷的数据会实时更新吗？** A: 取决于数据源。数据库节点每次运行时会实时查询最新数据，Excel 节点和联网搜索节点需要手动重新运行。 **Q: 一个画卷最多可以有多少个节点？** A: 建议不超过 20 个节点。过于复杂的流程应拆分为多个画卷。 # AI 索引 Source: https://docs.asktable.com/concepts/data/ai-search 介绍 AskTable 的 AI 索引功能，帮助用简称提问时自动映射为完整实体并生成正确查询，支持手动开关与统计查看以平衡准确性和性能。 私有部署（Docker）需要先部署 aisearch 才能使用本功能，见 [部署 AI 搜索](/deploy/ai-search)。 ## 功能简介 这个功能可以让你用简称提问，比如"阿里巴巴"或"Mate 40"，系统会自动将其转换为完整的公司或产品名称，并生成正确的查询语句，确保你能精准获取数据，适用于数据库中存储的是完整名称而用户习惯用简称提问的场景。 ## 如何使用该功能 在数据源详情页的 **数据概览** 标签页，选中一张表后，字段表格的 **AI 索引** 列即可逐个控制： * **默认设置**：系统会自动为部分字段启用 AI 索引。默认启用的是字符串类型的短文本，不包括长文本、日期、数字等类型。这些字段会帮助 AI 更准确地匹配用户问题。 * **手动配置**：点击字段对应的开关，即可开启或关闭该字段的 AI 索引。开启后开关旁会显示状态图标。 ## 查看 AI 索引详情 点击 AI 索引列的信息图标，可以查看该字段的索引状态和统计数据，包括： * 总记录数 * 索引值数量 * 去重数量 系统会根据这些统计数据判断字段是否符合 AI 索引要求。 ## 为什么需要开关按钮？ 在某些情况下，开启过多的索引会影响系统的性能，因为每个索引都需要消耗一定的计算资源。大量无关索引信息也会变成噪音，干扰 AskTable 对问题的分析和判断。所以我们为您提供了一个控制开关，让您可以根据实际需求开启或关闭某些字段的索引功能。 * **开启 AI 索引**：AI 将能更智能地理解和匹配您的问题，提高查询准确性。 * **关闭 AI 索引**：可以提高系统的性能，但可能牺牲一些查询的准确性。 ## 总结 * **默认开启**：适用于大多数场景，系统会自动开启某些字段的 AI 索引功能。 * **用户配置**：您可以手动开启或关闭字段的 AI 索引功能，灵活调整。 * **优化性能**：过多的索引可能会影响系统性能，建议根据需要进行配置。 通过配置 AI 索引功能，您可以提高 AI 查询的灵活性和准确性，同时根据实际需求优化系统性能。 ## 用户注意事项 * 开启 AI 索引功能可能会增加系统的计算负担，建议仅在必要时启用。 * 默认启用的字段已经过优化，适合大部分用户场景。 # 表、字段备注 Source: https://docs.asktable.com/concepts/data/annotations 说明如何在 AskTable 中为表和字段添加或编辑备注，利用元数据提升 AI 对业务含义的理解，生成更准确的查询结果。 元数据是对数据的"数据"描述，提供了数据的背景信息，如结构、格式和含义。这些信息让 AI 能够更准确地解读和处理数据，从而提升查询的精准度和效率。 AskTable 会自动从数据库中提取元数据，包括数据库、表、字段的信息，以及字段备注。即使没有备注，系统也会自动生成相关信息。所有元数据将汇总并存储在 AskTable 的 Meta Brain 中，为后续查询和分析提供支持。 ## 如何添加和编辑备注 进入数据源详情页的 **数据概览** 标签页，在左侧树形导航中选中一张表，右侧即可查看和编辑它的表描述与字段备注： * **表描述** — 字段表格上方的蓝色边框区块，点击其中的编辑图标即可修改。 * **字段备注** — 在字段表格的 **备注** 列，将鼠标移到对应单元格，点击编辑图标打开编辑框，输入或修改描述后保存。编辑框支持字符计数（上限 255）和 **AI 优化** 一键润色。 元数据在数据查询中的作用体现在多个方面，比如： **示例 1：枚举值** 例如，一个字段记录性别，其中 sex=1 表示男性，sex=2 表示女性。当用户查询"性别为男"的数据时，AI 会基于元数据自动生成查询条件 sex=1，无需用户明确说明。 **示例 2：特定格式** 例如，一个字段记录基金的星级评价，使用从 ★ 到 ★★★★★ 的格式。如果用户查询"四星以上的基金有多少"，元数据会帮助 AI 理解星级格式，自动生成正确的查询条件： * 错误：`select count(*) from fund where star >= 4;` * 正确：`select count(*) from fund where star in ('★★★★','★★★★★')` 通过元数据的加持，AskTable 能更深入地理解数据的实际含义，为您生成更精准的查询结果，助力高效决策。 ## 备注来源 备注列左侧的图标标识每个字段备注的来源： * **数据库图标** — 来自数据库的原始备注 * **机器人图标** — AI 自动生成 * **笔图标** — 人工标注 人工标注的备注最贴近业务语义，有助于 AI 更好地理解字段含义。 ## 批量更新描述 如果需要批量更新多个字段的描述，可通过元数据导出 / 导入完成： 1. 在数据概览页点击右上角 **···** 菜单，选择 **导出元数据**，将当前字段描述、字段可见性和训练数据保存为 JSON 文件 2. 用文本编辑器批量修改 JSON 文件中的描述内容 3. 返回数据概览页，选择 **导入元数据**，将修改后的文件导入 导入后，字段描述和可见性将被覆盖更新，训练数据则会追加。 # 连接 Google BigQuery Source: https://docs.asktable.com/concepts/data/bigquery 在 Google Cloud 中创建 Service Account 密钥，并在 AskTable 中连接 BigQuery 数据源。 AskTable 通过 Service Account（服务账号）密钥连接 Google BigQuery。整个过程分两步：先在 Google Cloud 创建一个具备只读权限的服务账号并下载 JSON 密钥，再把密钥粘贴进 AskTable。 ## 1. 创建 Service Account 密钥 打开 [Google Cloud Console](https://console.cloud.google.com)，在顶部选择目标项目，进入 **IAM 和管理 → 服务账号**，点击 **创建服务账号**，起一个名字（例如 `asktable-readonly`）。 为服务账号授予以下两个角色，这是 AskTable 只读问数所需的最小权限： | 角色 | 用途 | | ----------------------------------------------------- | --------- | | **BigQuery Data Viewer**（`roles/bigquery.dataViewer`） | 读取表数据和元数据 | | **BigQuery Job User**（`roles/bigquery.jobUser`） | 提交查询作业 | 如果只想开放个别 dataset，可以跳过项目级的 Data Viewer：在 BigQuery 控制台对目标 dataset 点击 **共享 → 添加主账号**，把 Data Viewer 授予该服务账号即可。Job User 仍需项目级授权。 进入刚创建的服务账号，切到 **密钥** 标签，点击 **添加密钥 → 创建新密钥**，类型选择 **JSON**。浏览器会自动下载一个 `.json` 密钥文件——它就是下一步要用的全部凭证。 两种情况会导致无法创建密钥：BigQuery 沙箱项目（未启用结算）不支持服务账号密钥；部分企业组织策略（`iam.disableServiceAccountKeyCreation`）禁用了密钥创建，遇到报错请联系你的 Google Cloud 管理员。 ## 2. 在 AskTable 中连接 在左侧主导航点击 **【更多】**，进入数据工作区后，点击侧边栏的 **【数据源】**，再点击右上角 **【添加数据】**。在**大数据**分类下选择 **Google BigQuery**，填写连接信息： | 字段 | 说明 | | ------------------------ | ------------------------------------------------------ | | **数据名称** | 可选，留空将自动生成 | | **Service Account JSON** | 粘贴密钥文件的完整内容，或点击 **【上传 JSON 文件】** 选择刚下载的 `.json` 文件自动填充 | 不需要填写主机、端口或项目 ID——AskTable 会从密钥中自动识别 GCP 项目。 点击 **【立即添加】**，系统会自动测试连接。连接成功后进入选表页面，勾选需要引入的数据表（BigQuery 的 dataset 对应这里的 schema 层级）。 密钥在 AskTable 中加密存储，任何页面和接口都不会回显。后续如需更换密钥，在数据源详情页的连接配置中重新粘贴即可，留空表示保持不变。 ## 常见问题 | 现象 | 原因与处理 | | ----------------- | ----------------------------------------------------------------------------------- | | 提示凭证格式不正确 | 粘贴的内容不是完整的 JSON，或缺少 `project_id` / `client_email` / `private_key` 字段。请重新复制整个密钥文件的内容 | | 连接测试报认证失败 | 密钥已被撤销或删除。在 Google Cloud 重新创建一个密钥 | | 连接测试报权限不足 | 服务账号缺少 **BigQuery Job User** 角色，无法提交查询 | | 选表页面看不到某个 dataset | 服务账号对该 dataset 没有 **BigQuery Data Viewer** 权限，按第 1 步为它补充授权 | ## 后续步骤 * [管理数据](/concepts/data/manage) — 查看和管理已连接的数据源 * [表、字段备注](/concepts/data/annotations) — 添加表和字段的业务描述，提升 AI 理解准确度 # 连接数据源 Source: https://docs.asktable.com/concepts/data/connect 介绍如何在 AskTable 中添加数据源，支持 30+ 种数据库和文件类型。 AskTable 支持 30+ 种数据库和文件类型，覆盖主流关系型数据库、大数据引擎和文件导入。 ## 1. 进入数据源管理 在左侧主导航点击 **【更多】**，进入数据工作区后，点击侧边栏的 **【数据源】**，进入数据源列表页。列表页顶部有按名称过滤的搜索框，右上角是 **【添加数据】** 按钮。 点击 **【添加数据】**，进入创建流程。 ## 2. 选择数据类型 创建流程的第一步是选择数据类型。AskTable 支持 30+ 种数据源，分**文件**、**数据库**、**大数据**三大类。完整清单如下： **文件** Excel（`.xlsx` / `.xls`）、CSV、飞书多维表格、工作簿（内置可写数据集，Beta） **关系型数据库** MySQL、PostgreSQL、Oracle、Microsoft SQL Server、TiDB、OceanBase、PolarDB（MySQL / PostgreSQL 版）、Greenplum **国产 / 信创数据库** 达梦（DM）、人大金仓 KingbaseES、南大通用 GBase（8a / 8c）、虚谷 XuGu、雅山 YashanDB、MogDB、华为 GaussDB、腾讯 TDSQL（MySQL / PostgreSQL 版） **大数据与数据仓库** ClickHouse、StarRocks、Apache Doris、SelectDB、Apache Hive、阿里云 MaxCompute、Hologres、Databend、阿里云 AnalyticDB（MySQL / PostgreSQL 版）、GaussDB(DWS)、[Google BigQuery](/concepts/data/bigquery) **版本兼容**：AskTable 通过 SQL 方言适配连接各引擎，对常见版本广泛兼容，无需指定具体版本。已在测试中验证的版本有 MySQL 8、PostgreSQL 16、Oracle 11g、SQL Server 2022，以及 StarRocks、Apache Doris、SelectDB、Databend、AnalyticDB MySQL 等。达梦需使用企业版。 ## 3. 配置连接信息 选择一个数据库类型后，填写连接信息： | 字段 | 说明 | | ------------ | ------------------------------------------------------------ | | **数据名称** | 可选，留空将自动生成 | | **主机** | 数据库服务器地址 | | **端口** | 自动填充该引擎的默认值，可按需修改 | | **用户名 / 密码** | 数据库认证信息 | | **数据库 DB** | 要连接的数据库名称。部分引擎（如 MySQL）可填多个库，用英文逗号分隔；Oracle 此处填 Service Name | 不同引擎的字段略有差异，例如 Oracle 用 Service Name，Databend 需额外填写计算集群；Google BigQuery 不用主机和端口，改用 Service Account 密钥连接，详见[连接 Google BigQuery](/concepts/data/bigquery)。表单会按所选引擎自动调整。 填写完成后点击 **【立即添加】**，系统会自动测试连接。连接成功后进入选表页面。 ## 4. 添加数据表 连接成功后，系统会列出数据库中的表和视图。勾选需要引入的数据表，点击 **【确认选择】**；也可点击 **【跳过】**，后续在数据概览页中重新选择。 这一步还可以勾选 **【同步 Value Index】**，为字段值构建检索索引、提升字段值检索精度。构建较耗时，建议仅在数据量较小或检索要求高时开启，也可在创建后再手动触发。 ## 文件上传 如果选择的是 **Excel / CSV** 文件类型，第二步将变为文件上传页面： 1. 填写数据名称（可选） 2. 拖拽或点击上传 `.xlsx` / `.xls` / `.csv` 文件，支持同时上传多个文件（最多 10 个，Excel 单文件最大 10MB，CSV 最大 20MB） 3. 点击 **【立即添加】** 完成创建 上传完成后直接回到数据源列表页。 ## 后续步骤 了解如何管理和使用这些数据，请参阅以下文档： * [管理数据](/concepts/data/manage) — 查看和管理已连接的数据源 * [表、字段备注](/concepts/data/annotations) — 添加表和字段的业务描述，提升 AI 理解准确度 # 字段隐藏 Source: https://docs.asktable.com/concepts/data/hidden-fields 介绍如何在 AskTable 中隐藏不相关或敏感字段，使 AI 查询时忽略这些列，以保障隐私并提升分析效率。 ## 功能简介 字段隐藏功能允许您在 AI 查询时忽略某些字段。当某个字段被设置为隐藏后，AI 在分析和回答问题时将不会考虑该字段的数据，这对于排除不相关或敏感字段非常有用。 ## 如何使用该功能 进入数据源详情页的 **数据概览** 标签页，在左侧选中一张表，右侧字段表格的 **隐藏** 列即可逐个控制： 1. 找到您想要隐藏的字段 2. 在 **隐藏** 列中点击开关将其打开 3. 开关即时生效，AI 在回答问题时将忽略该列数据 ## 使用场景 * **排除敏感信息**：隐藏包含敏感数据的字段，避免 AI 在处理查询时使用这些信息 * **提高查询效率**：隐藏不相关的字段可以减少 AI 分析的数据量，提高查询性能 * **简化数据分析**：对于不需要参与分析的辅助字段，可以将其隐藏以简化数据结构 ## 注意事项 * 隐藏字段后，AI 在生成查询语句和回答问题时将完全忽略该字段 * 隐藏操作是即时的，无需额外保存 * 如果后续需要该字段参与分析，可以随时取消隐藏 * 如需对字段做脱敏而非完全隐藏（例如手机号、身份证号），可改用字段表格的 **脱敏加密** 列 # 管理数据 Source: https://docs.asktable.com/concepts/data/manage 在 AskTable 中查看、维护数据源及其元数据配置，包括基本信息、连接配置、字段配置、训练集等，保障查询准确性与数据安全。 数据源创建完成后，可在数据源详情页维护其元数据和配置。完善的配置能让 AI 更好地理解业务字段语义，提供更准确的分析结果。 ## 进入数据源列表 在左侧主导航点击 **【更多】**，进入数据工作区后，点击侧边栏的 **【数据源】**，进入数据源列表页。 列表以卡片网格展示，每张卡片包含： * **引擎图标 + 名称 + 引擎标签** — 数据源名称和它的数据库/文件类型 * **状态标记** — 元数据是否可用、是否同步处理中 * **描述** — 数据源的业务描述 * **表数量**（数据库类型还会显示 schema 数量）和**更新时间** 将鼠标移到卡片上，右上角会出现 **···** 菜单： * **快速对话** — 跳转到对话页面，基于该数据源直接提问 * **删除数据** — 删除该数据源 点击卡片进入该数据源的**详情页**。 ## 详情页头 详情页顶部是数据源概览区：面包屑（**全部数据 / 当前数据源**）、引擎图标、名称、引擎标签、描述，以及一行元数据——可复制的数据源 **ID**、schema / 表 / 字段数量、可用状态、创建时间。 右上角是操作按钮： * **连接配置**（仅数据库类型）— 打开连接信息编辑弹窗 * **编辑** — 修改基本信息 * **···** — 展开菜单，包含 **构建 Value Index** 和 **删除数据源** ## 编辑基本信息 点击页头的 **【编辑】** 按钮，打开基本信息弹窗，可修改： * **数据名称** — 数据源的显示名称 * **描述** — 数据源的业务描述，有助于 AI 理解数据背景 ## 编辑连接配置（仅数据库类型） 数据库类型的数据源，点击页头的 **【连接配置】** 按钮，可修改连接信息：主机、端口、用户名、密码、数据库。密码留空则不修改。保存后系统会重新测试连接并同步元数据。 ## 详情页的标签页 详情页用标签页组织内容： * **数据概览** — 始终显示，元数据与字段配置的核心区域 * **文件管理** — 仅文件类型（Excel / CSV）显示 * **训练集** — 始终显示 因此数据库类型有「数据概览、训练集」两个标签页；文件类型有「数据概览、文件管理、训练集」三个标签页。 ## 数据概览与字段配置 数据概览是详情页的默认标签页，也是**最核心的配置区域**。 工具条左侧是「数据概览」标题和同步状态徽标；右侧有 **【重新选表】** 按钮（仅数据库类型，用于增删需要同步的表）和 **···** 菜单（导出 / 导入元数据）。 ### 页面结构 * **左侧树形导航** — 按 schema → 表的层级组织，点击表名在右侧查看其字段 * **右侧** — 顶部是选中表的**表描述**（蓝色边框区块，点击编辑图标可修改），下方是字段表格 ### 字段配置 字段表格包含以下列： | 列 | 说明 | | --------- | -------------------------------------------------------------------- | | **列名** | 数据库中的原始字段名 | | **备注** | 字段的业务含义描述。左侧图标标识来源：数据库图标（数据库原始备注）、机器人图标（AI 自动生成）、笔图标（人工标注）。点击编辑图标可修改 | | **隐藏** | 开关。隐藏后，AI 识别时会忽略该字段，适用于密码、内部 ID 等敏感或无关字段 | | **AI 索引** | 开关。开启后 AI 会为该字段值生成语义索引，提高自然语言查询的命中率。点击信息图标可查看索引统计 | | **脱敏加密** | 下拉选择。对包含隐私数据的字段进行脱敏，支持人名、手机号、身份证号、银行卡号、邮箱 | | **更新时间** | 该字段配置最后修改的时间 | 各项的详细说明见 [表、字段备注](/concepts/data/annotations)、[字段隐藏](/concepts/data/hidden-fields)、[AI 索引](/concepts/data/ai-search)。 ## 文件管理（仅文件类型） Excel / CSV 类型的数据源，详情页有 **【文件管理】** 标签页： * **文件列表** — 显示已上传的文件，支持预览、下载、删除 * **上传新文件** — 拖拽或点击上传 `.xlsx`、`.xls`、`.csv` 文件，支持同时上传多个 * 有改动后点击 **【保存修改】** 生效 ## 训练集 训练集标签页用于管理该数据源专属的问答训练数据。每条训练数据包含： * **用户问题** — 自然语言问题 * **正确 SQL** — 对应的正确 SQL 语句 * **来源** — `手动添加` 或 `点赞反馈`（从对话中点赞收集） * **创建时间** * **是否启用** — 开关，控制该条训练数据是否生效 训练数据可以帮助 AI 学习特定的查询模式和业务术语，提升回答准确度。 ## 元数据导入 / 导出 在数据概览页的 **···** 菜单中： * **导出元数据** — 将字段描述、字段可见性、训练数据等配置导出为 JSON 文件 * **导入元数据** — 导入 JSON 文件，覆盖字段描述与可见性，并追加训练数据 ## 删除数据源 点击页头的 **···** 菜单，选择 **【删除数据源】**，确认后该数据源及其所有配置将被永久删除。数据库类型的数据源被删除后，不会影响数据库中的实际数据。 ## 后续步骤 * [表、字段备注](/concepts/data/annotations) — 添加表和字段的业务描述，提升 AI 理解准确度 * [字段隐藏](/concepts/data/hidden-fields) — 控制哪些字段对 AI 可见 * [AI 索引](/concepts/data/ai-search) — 为字段值生成语义索引，提高查询命中率 # 企业集成登录 Source: https://docs.asktable.com/concepts/organization/enterprise-login 为组织配置企业微信或 WPS，预导入成员，并使用绑定组织的回调地址登录。 企业微信和 WPS 是**组织级身份集成**。每个组织独立保存自己的 CorpID/AppID 和应用密钥，不会与其他组织共享企业身份命名空间。Owner 和 Admin 可以配置；不受 Cloud 套餐限制，私有部署也可使用。 创建自建应用，配置可见范围和应用主页，再启用登录与成员导入。 创建企业自建应用，配置权限和回调地址，再启用登录与成员导入。 ## 连接企业应用 进入 **个人设置 → 组织 → 登录集成**，选择企业微信或 WPS： * 企业微信按 [连接企业微信](/how-to/connect-wecom) 操作； * WPS 按 [连接 WPS](/how-to/connect-wps) 操作； * 企业微信填写 CorpID、AgentID 和 Secret； * WPS 填写 AppID 和 AppKey； * 首次连接必须填写密钥；保存后密钥不会显示，后续留空表示保持原值； * CorpID/AppID 保存后不能直接修改。切换企业时先断开，再重新连接。 详情页会给出回调地址。把它登记到企业应用后台；该地址也可以直接发给组织成员作为登录入口。 Local 回调地址形如 `/login/sso/wecom` 或 `/login/sso/wps`，由后端绑定唯一的 default org；Cloud 地址会附带 `?org_id=...` 来指定组织。两种地址都不是邀请链接，不会自动加入新成员。 ## 选择导入成员 点击 **导入成员** 后，AskTable 会读取应用当前可见用户。你可以按姓名或外部 UID 搜索、按状态筛选并逐人勾选；已导入和已停用成员不能选择。页面会同时显示当前上限、剩余名额和本次选择将占用的名额。 提交时后端会重新读取可见范围和容量。若成员已不可见、状态已变化或名额不足，整批不会写入，页面会刷新候选供你重新调整。成功导入只执行新增： * 新外部身份创建全局 User 和带企业租户范围的登录凭证，并以 Member 加入当前组织； * 已存在的同租户身份复用 User；已有 active membership 和角色保持不变； * 已停用 membership 不会自动恢复； * 不会因为上游通讯录删除成员而自动停用 AskTable 成员； * 新增人数受组织成员上限约束。 只有已经导入、User 为 active 且当前组织 membership 为 active 的成员可以通过专属链接登录。首次企业登录不会即时创建成员；本期也不提供组织搜索、域名发现或 SCIM。 只绑定企业微信/WPS、没有邮箱凭证的 User 不能创建组织或成为 Owner。若要转让 Owner，目标用户必须已经拥有邮箱凭证。 ## 断开连接 断开只删除当前组织的集成配置。已有 User、外部身份凭证、membership、项目和历史内容都会保留，但该组织的企业登录入口会立即停止工作。重新连接相同企业并再次导入后可以继续复用原身份。 部署级 Google、GitHub、微信和邮箱登录不在这里配置，详见 [部署认证配置](/deploy/authentication)。 # 邀请成员 Source: https://docs.asktable.com/concepts/organization/invitations 使用组织直接邀请、组织公开链接、项目公开链接和项目成员添加。 AskTable 把组织邀请和项目加人分开处理：组织直接邀请可以发给尚未注册的人，并在创建时预留成员额度；项目主动加人只面向已注册用户并立即生效。公开链接不预留额度，在实际加入时检查。 ## 组织直接邀请 直接邀请绑定一个登录标识：国内 Cloud 使用手机号，海外 Cloud 和私有部署使用邮箱。 * 有效期为 7 天； * 只能接受一次； * 可以邀请尚未注册 AskTable 的人； * 受邀人注册后，系统会自动匹配仍有效的邀请。 Owner 可以邀请 Admin、Billing Admin、Member 或 Guest；Admin 只能邀请 Member 或 Guest。创建后，待接受成员会立即出现在成员目录中，并预留一个成员额度（Billing Admin 不占额度）。撤销或过期会释放额度；接受时只把预留转成正式成员，不重复计数。 ## 公开链接 公开链接不会自动过期，一直有效到管理员关闭或重置。 | 链接类型 | 接受后的身份 | | ------ | ---------------------- | | 组织公开链接 | 组织 Member | | 项目公开链接 | 组织 Guest + 目标项目 Member | 组织公开链接默认关闭。在 **成员管理** 中开启后才会生成链接；再次关闭会立即让它失效。只有开启时才显示链接、“复制”和“重置”。重置会生成新链接，旧链接立即失效。 项目公开链接保留在项目设置中，始终授予项目 MEMBER。需要 ADMIN 时，项目负责人或管理员可以主动添加已注册用户并选择 ADMIN，或者在对方加入后修改角色。 ## 项目成员添加 项目负责人和项目管理员可以输入完整邮箱或手机号，精确查找全站已注册用户。系统不会提供模糊用户列表，也不能为未注册身份创建项目 pending 邀请。 * 组织内 active 成员：保留组织角色，只增加显式项目角色； * 组织外用户：立即成为组织 Guest，并加入目标项目； * 已停用成员：恢复为 Guest 后加入项目； * Billing Admin：不能被添加为项目成员。 整个操作在一个事务中完成；成员额度不足时不会留下组织成员或项目角色。 ## 接受邀请 组织直接邀请可在站内接受；公开链接可直接从浏览器打开。 未登录用户先登录，尚未注册的用户可切换到注册。邮箱登录、邮箱注册、SSO、手机号绑定和用户资料引导都会保留完整链接。 认证完成后系统自动接受公开链接。组织链接进入组织，项目链接直接进入目标项目，无需再次点击确认。 已经是 active 组织成员的人打开同一组织链接时不会改变角色或重复计费，系统会直接进入组织并提示“已经加入该组织了”。无效、已关闭、已重置或额度已满的链接会停留在错误页面，可手动重试。 当前版本只提供站内组织直接邀请和复制公开链接，不自动发送短信或邮件。 # 成员与角色 Source: https://docs.asktable.com/concepts/organization/members-and-roles 了解组织角色、项目角色、成员额度和 Owner 转让规则。 组织角色决定成员能管理什么；项目角色决定成员能在某个项目中做什么。 ## 组织角色 | 角色 | 能力 | 占成员额度 | | ------------- | ------------------------- | ----: | | Owner | 全部组织治理、成员、项目、套餐和用量 | 是 | | Admin | 成员、项目元数据和用量治理；不能删除组织或管理账单 | 是 | | Billing Admin | 套餐购买和用量；不能进入项目 | 否 | | Member | 使用已加入的项目；不能查看组织用户目录 | 是 | | Guest | 只使用被邀请加入的项目 | 是 | 每个组织始终只有一个 Owner。已停用成员不占额度；尚未接受且仍有效的组织直接邀请会预留额度，Billing Admin 邀请除外。 ## 项目角色 项目角色只有： * **项目负责人（OWNER）**：每个项目恰好一人，可管理访问策略、项目和成员； * **项目管理员（ADMIN）**：可管理项目资源； * **项目成员（MEMBER）**：可问数和使用项目内共享资源。 组织 Owner/Admin 可以治理组织内全部项目，但不会自动获得项目内容角色。项目内容的有效角色按以下优先级解析： 1. 显式项目角色； 2. 如果是公开项目，active Org Owner/Admin/Member 使用项目默认 ADMIN 或 MEMBER； 3. 其他情况无访问权。 因此显式角色可以覆盖默认角色，既可以升级也可以降级。Guest 始终需要显式角色，Billing Admin 不能成为项目成员。 ## Cloud 角色能看到哪些组织页面 | 页面 | Owner | Admin | Billing Admin | Member | Guest | | ---- | ----: | ----: | ------------: | -----: | ----: | | 组织设置 | ✓ | ✓ | ✓（仅套餐区） | | | | 项目管理 | ✓ | ✓ | | | | | 成员管理 | ✓ | ✓ | | | | | 用量 | ✓ | ✓ | ✓ | | | 私有部署不显示 Guest、Billing Admin 和组织用量页。 组织成员管理操作 membership 与组织直接邀请，包括组织角色、停用与 Owner 转让；它不修改登录邮箱、密码或 SYS\_ADMIN 身份，也不删除全局 User。项目主动加人是已注册用户的即时操作，不会在组织成员目录中创建项目 pending 邀请。 ## 停用与退出 停用成员会立即取消其组织和项目访问权，但保留成员记录及其历史内容。以后再次邀请同一成员时，可以恢复关系。 Owner 不能直接退出或被停用。要离开组织，必须先把 Owner 转让给一名 active Admin 或 Member。转让完成后，原 Owner 自动变为 Admin。 同样，仍是任一项目负责人的用户不能退出组织、被停用、改为 Billing Admin 或删除账号。请先把每个项目转让给 active 且已显式加入该项目的 Admin 或 Member；项目转让后，原负责人变为项目 Admin。 修改角色或转让 Owner 前，请确认目标成员身份正确。Owner 转让会立即改变组织治理权限。 # 组织与项目 Source: https://docs.asktable.com/concepts/organization/overview 了解 AskTable 中组织、项目和账号的关系，以及如何切换组织和创建项目。 组织（Organization）是 AskTable 中管理成员、项目、套餐和用量的主体。一个账号可以加入多个组织，每个项目只属于一个组织。 ```text theme={null} 账号 → 组织 → 项目 → 数据源、智能体、对话、Dashboard ``` ## Cloud 与私有部署 | 能力 | Cloud | 私有部署 | | --------------------- | ----------- | ---------------- | | 组织数量 | 可创建或加入多个 | 固定一个 default org | | 组织切换 | 支持 | 不需要 | | Guest / Billing Admin | 支持 | 不提供 | | 组织账单 | Free / Team | 使用私有部署 License | ## 切换组织 在左下角打开个人卡片，选择组织名称即可切换。项目列表、当前项目记忆、账单和用量都会跟随当前组织变化，不会混用其他组织的数据。 私有部署只有一个组织，因此个人卡片不显示组织切换菜单，也不提供单独的组织治理入口。请先从个人卡片进入 **个人资料**，再使用个人设置侧栏的 **组织** 分组。 如果账号还没有加入任何组织，登录后会进入组织引导页。你可以： * 创建一个新组织； * 接受别人发来的邀请； * 打开组织或项目邀请链接。 ## 项目可见范围 项目分为两类： * **公开项目**：组织内 active Owner、Admin 和 Member 按项目设置的默认“管理员”或“成员”权限进入； * **私密项目**：只有被显式加入项目的人可以进入； * Guest 不继承公开项目默认权限，仍须显式加入； * Billing Admin 只能查看和管理套餐、查看用量，不能进入项目。 “公开”只表示对当前组织内的正式成员公开，不代表互联网公开。显式项目角色始终优先于公开项目默认权限：默认成员可以被显式提升为管理员，默认管理员也可以被显式降为成员；移除显式角色后恢复当前默认权限。 Owner 和 Admin 始终可以创建项目。Member 是否可以创建项目，由组织设置中的“允许成员创建项目”控制。 ## 管理入口 Owner 和 Admin 可在个人设置中进入 **组织信息**、**项目管理**、**成员管理**、**用量**和**登录集成**。Billing Admin 只显示 **组织信息**和**用量**；组织设置中只展示套餐、到期信息和配额，不展示组织基本信息。项目管理可创建、重命名项目，并治理显式项目成员与负责人；没有有效项目角色的组织管理员只能治理，不能打开项目内容。项目负责人还可以在具体项目设置中修改项目类别和默认权限。成员管理只处理组织邀请、组织角色、停用和 Owner 转让，不会修改账号邮箱、密码或系统管理员身份。 Cloud 的 SYS\_ADMIN 仍可在系统设置中管理全局项目和全局用户，这与当前组织的数据范围不同。私有部署不提供这两个系统级入口，用户和项目统一在唯一组织内管理。私有部署的 SYS\_ADMIN 还可以在个人设置的 **组织信息** 中查看体验版或 License 状态，并激活或更新企业许可证。 Owner/Admin 还可以从 **登录集成** 进入企业集成页面，连接企业微信或 WPS、预导入成员并复制回调地址作为登录入口。Google、GitHub、微信、邮箱与 SMTP 是部署级环境配置，不再位于系统设置中。 ## 对话与 Dashboard 对话和 Dashboard 默认仅创建者可见。具有有效项目负责人或项目管理员角色的人可以查看项目内全部内容；组织 Owner/Admin 只有在获得显式项目角色或公开项目默认管理员角色后才具备这项内容权限。需要让其他人查看时，请使用分享链接。 分享链接不会把访问者加入组织或项目。组织被暂停或删除后，已有分享链接也会停止工作。 ## 下一步 * [成员与角色](/concepts/organization/members-and-roles) * [邀请成员](/concepts/organization/invitations) * [企业集成登录](/concepts/organization/enterprise-login) * [套餐与用量](/concepts/organization/plans-and-usage) # 套餐与用量 Source: https://docs.asktable.com/concepts/organization/plans-and-usage 了解 Free、Team、月度 credits、加购 credits 和组织只读状态。 Cloud 组织只有 Free 和 Team 两档。套餐按组织生效，不是个人会员，也不按成员人数单独计价。 | 能力 | Free | Team | | --------------- | ---: | -------------: | | active 成员上限 | 3 | 20 | | 项目上限 | 1 | 5 | | 组织 Workbook 总上限 | 1 | 5 | | 每月 credits | 10 | 10000 | | 价格 | 免费 | ¥200/月、¥1680/年 | 两个套餐的项目资源上限相同：每项目 50 个数据源、5 个角色、10 个策略、10 个 API Key。均没有 rate limit 或额外功能门控。 Owner、Admin 和 Billing Admin 可以在 **设置 → 组织** 查看当前套餐、Team 到期日、成员、项目、Workbook、月度 credits 和加购 credits。Owner 与 Billing Admin 还可以在这里兑换、升级或续费；Team 状态下也可以购买加购 credits。Admin 只能查看。Free 下已有加购余额会显示为冻结。 ## Credits 如何扣除 每个组织有两个 credit 池： 1. 先扣每月发放的周期 credits，周期结束不结转； 2. 周期池不足时，再扣已购买的加购 credits。 真正会消耗 credits 的操作在余额不足时会被阻止。读取数据、管理成员、查看用量、续费和购买不会因此被锁定。 Team 可以按 ¥1=10 credits 购买加购包，最低 100 credits。降级到 Free 后，加购余额会保留但暂时不可用；重新升级 Team 后恢复。 ## 升级、续费和到期 * Free 升 Team 立即开始新的月周期并发放 10000 credits；Free 剩余周期 credits 作废。 * Team 续费只延长到期日，不会重置当前月的 credits。 * Team 到期后自动降为 Free，并开始新的 Free 月周期、发放 10 credits。 ## 超出降级上限 如果降级后成员数或项目数超过 Free 上限，组织会进入只读状态。此时仍可续费、停用成员和删除项目；恢复到上限内后自动解除。Workbook 超额只阻止继续创建 Workbook，不会锁住整个组织。 Owner 和 Admin 可以从 **组织 → 项目 → 编辑** 给当前项目设置月度 credit 配额。留空表示使用共享组织池；达到项目配额后，只阻止该项目继续消耗 credits，其他项目仍可使用组织余额。 ## 查看用量 Cloud 的 Owner、Admin 和 Billing Admin 可以在 **组织 → 用量** 查看： * 当前周期总览； * 可按项目或按人统计用量，并独立选择最近 24 个 UTC 小时、7 天或 30 天； * 同一份聚合数据的图表或明细视图；按成员或凭证时也会标识成员、API Key、系统和迁移前计费归属。 私有部署不提供组织用量页。 API Key 仍按项目管理。组织用量页不提供跨项目 API Key 清单；需要创建、查看或停用 API Key 时，请进入对应项目的设置页。 迁移前无法识别真实操作者的记录会显示为“迁移前计费归属”，不会冒充某位成员。 # 进阶配置 Source: https://docs.asktable.com/deploy/advanced 子路径部署与白标定制等进阶配置，面向已获取商业授权的私有部署。 本页的配置面向**已获取商业授权**的私有部署。授权方式见 [商业授权](/deploy/license)。 ## 子路径部署 想把 AskTable 挂在某个子路径下（如 `https://example.com/asktable`），给 [私有部署](/deploy/docker) 的 `asktable` 服务加上 `BASE_PATH`，并加一个 Caddy 反代： ```yaml theme={null} services: asktable: environment: BASE_PATH: /asktable # 子路径前缀 caddy: image: caddy:2-alpine container_name: caddy restart: unless-stopped ports: - "8080:80" volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro depends_on: - asktable ``` 同目录下新建 `Caddyfile`： ```text Caddyfile theme={null} :80 { redir /asktable /asktable/ permanent handle /asktable/* { uri strip_prefix /asktable reverse_proxy asktable:80 } } ``` 之后通过 `http://<服务器>:8080/asktable/` 访问。生产环境一般在最外层再接你自己的网关，用 80/443 暴露。 ## 白标定制 在 `asktable` 服务的 `environment` 下设置品牌信息： ```bash theme={null} APP_NAME=MyBrand # 侧边栏、分享页等处的品牌名 APP_TITLE=我的应用 # 浏览器标签标题 APP_DESCRIPTION=应用描述 # SEO 描述 ``` 替换 logo 和 favicon（卷挂载到 `asktable` 服务）： ```yaml theme={null} services: asktable: volumes: - ./asktable_data:/asktable - ./mylogo.png:/usr/share/nginx/html/logo.png:ro - ./myfavicon.png:/usr/share/nginx/html/favicon.png:ro ``` 设置了 `APP_NAME` 建议同时挂载自定义 logo，否则品牌名会与默认 logo 视觉不搭。 # AI 搜索（值索引） Source: https://docs.asktable.com/deploy/ai-search AI 搜索（值索引）是私有部署里的可选组件，靠 aisearch 搜索引擎把字段值建成索引，让用简称提问也能命中数据库里存的完整值。本页说明如何在 compose 里启用。 AskTable 的 **AI 搜索（值索引）** 是私有部署里的**可选组件**，为「[AI 索引](/concepts/data/ai-search)」这个能力提供后端支撑：它把表里字符串字段的**去重值**建成索引，用户用简称或口语（"阿里巴巴"、"Mate 40"）提问时，自动匹配到数据库里真实存的完整值，生成正确的查询条件。 底层由 **aisearch** 搜索引擎承载。**不部署 aisearch 时这个功能整体不可用**——控制台里给字段开「AI 索引」会提示未启用，问数时也不会做值匹配（其它功能不受影响）。 ## 在 compose 里启用 分两步：加一个 aisearch 服务，再把它的地址和密钥告诉 `asktable`。 ### 1. 加 aisearch 服务 给 [私有部署](/deploy/docker) 的 `docker-compose.yaml` 加上这个服务： ```yaml theme={null} services: # aisearch 搜索引擎（可选）：值索引的存储与检索 asktable-aisearch: image: registry.cn-shanghai.aliyuncs.com/dminfra/aisearch:v1.12.8 container_name: asktable-aisearch restart: unless-stopped environment: MEILI_MASTER_KEY: asktable-aisearch-master-key # 【建议修改】至少 16 字节 MEILI_ENV: production # 生产模式：强制鉴权、关闭搜索预览页 MEILI_NO_ANALYTICS: "true" # 关闭遥测上报 volumes: - ./aisearch_data:/meili_data # 索引数据持久化（引擎数据目录） ``` 它只在 compose 内部网络里被 `asktable` 访问，**不用对外暴露端口**。 ### 2. 让 asktable 用上它 在 `asktable` 服务的 `environment` 里加两个变量，并在 `depends_on` 里加上它： ```yaml theme={null} services: asktable: depends_on: - asktable-aisearch # 追加这一行 environment: AISEARCH_HOST: http://asktable-aisearch:7700 AISEARCH_MASTER_KEY: asktable-aisearch-master-key # 必须与上面 MEILI_MASTER_KEY 完全一致 ``` `AISEARCH_MASTER_KEY` 必须和上面 aisearch 的 `MEILI_MASTER_KEY` **一字不差**，否则 asktable 连不上，功能仍然不可用。生产环境务必把示例里的默认密钥换成自己的随机串（`MEILI_ENV: production` 下密钥至少 16 字节，否则 aisearch 拒绝启动）。 改完执行 `docker compose up -d` 生效。 ## 建立与重建索引 两个环境变量配好后，AI 搜索才真正启用。索引由后台任务异步构建，跑在既有的 `asktable-redis` 队列上，无需额外组件： * **逐字段开关**：进数据源的**数据概览**标签页，选中一张表，在字段表格的「AI 索引」列逐个开启——用法和统计详情见 [AI 索引](/concepts/data/ai-search)。 * **整源构建 / 重建**：需要一次性为某个数据源重建全部值索引时，在数据源页点「构建 Value Index」即可。 默认只为**短文本字符串字段**建索引（长文本、日期、数字不建）。单个数据源可建值索引的字段数有上限（默认 10 个），可在管理后台调整；单字段保留的去重值数量也有上限。这些限制是为了避免索引过多拖慢系统、引入噪音。 aisearch 自包含、运行期不外呼，适合完全离线 / 内网部署。 ## 下一步 * [AI 索引](/concepts/data/ai-search) — 这个功能怎么用、字段怎么选 * [私有部署（Docker）](/deploy/docker) — 部署 AskTable 本体 # 部署认证配置 Source: https://docs.asktable.com/deploy/authentication 通过静态环境变量配置 Google、GitHub、微信、邮箱登录、SMTP 和 SMS。 Google、GitHub、微信、邮箱登录、SMTP 与 SMS 属于整个 AskTable 实例，只从环境变量读取。修改后需要重启 Web 和 Worker；系统设置中不再提供这些认证配置。 ## OAuth 提供商 | 提供商 | 环境变量 | | ------ | ----------------------------------------- | | Google | `GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET` | | GitHub | `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET` | | 微信 | `WECHAT_APP_ID`、`WECHAT_APP_SECRET` | 每组 ID 和 Secret 必须同时设置。整组留空会禁用该提供商，只填一项会让应用在启动时失败并指出不完整配置。 ```yaml docker-compose.yaml theme={null} services: asktable: environment: GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-} GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-} GITHUB_CLIENT_ID: ${GITHUB_CLIENT_ID:-} GITHUB_CLIENT_SECRET: ${GITHUB_CLIENT_SECRET:-} WECHAT_APP_ID: ${WECHAT_APP_ID:-} WECHAT_APP_SECRET: ${WECHAT_APP_SECRET:-} SMS_API_URL: ${SMS_API_URL:-} SMS_API_KEY: ${SMS_API_KEY:-} ``` `GET /system/info` 只返回启用状态和非敏感 Client ID，不返回 Secret，也不包含任何组织级企业微信/WPS 配置。 ## 国内云 Cloud + CN 生产只允许微信登录。微信、企业微信或 WPS 认证成功后先建立正常会话；缺少手机号时，统一 setup 页面会要求完成验证后才能进入产品工作区。启动时必须同时配置 `WECHAT_APP_ID`、`WECHAT_APP_SECRET`、`SMS_API_URL` 和 `SMS_API_KEY`；任一缺失都会让进程明确报错并停止。 `make dev PROFILE=cn` 默认使用 `AT_DEV_MODE=1`，无需连接微信或短信服务。登录页仍使用生产微信扫码布局，只在二维码与协议下方附加“开发者登录”。点击后输入测试用户名：相同用户名复用同一模拟账号，不同用户名创建不同账号。首次登录建立正常会话后进入生产手机号绑定页，随机验证码只写入 server 日志。未配置微信 AppID 时原二维码槽位显示未配置状态；配置后可以同时使用真实二维码。共享开发或预发应设置 `AT_DEV_MODE=0` 并补齐四项生产配置。 ## 邮箱登录与 SMTP ```yaml docker-compose.yaml theme={null} services: asktable: environment: EMAIL_LOGIN_ENABLED: "true" EMAIL_SMTP_PROVIDER: aliyun # aliyun | custom EMAIL_SMTP_HOST: "" # custom 时必填 EMAIL_SMTP_PORT: "465" EMAIL_SMTP_USERNAME: "" EMAIL_SMTP_PASSWORD: ${EMAIL_SMTP_PASSWORD:-} EMAIL_SMTP_USE_SSL: "true" EMAIL_SENDER_ADDRESS: noreply@example.com ``` `aliyun` 使用固定的阿里云邮件推送主机和 SSL 端口，发件地址同时作为用户名；`custom` 使用给定的 Host、Port 与 SSL 选项，Username 留空时回退到发件地址。SMTP 未完整配置时，依赖邮件发送的任务会跳过邮件投递。 若 Google、GitHub、微信全部未启用，即使 `EMAIL_LOGIN_ENABLED=false`，系统也会保留邮箱登录兜底，避免部署完全没有登录入口。组织级企业微信/WPS 不参与这个判断。 企业微信和 WPS 请由组织 Owner/Admin 在企业集成中连接，参见 [企业集成登录](/concepts/organization/enterprise-login)。旧版本升级要求见 [迁移](/deploy/migration)。 # 私有部署（Docker） Source: https://docs.asktable.com/deploy/docker 用 Docker Compose 把 AskTable 完整部署到自己的服务器，数据不出内网。提供完整 docker-compose、访问与升级方法。 AskTable 支持完全私有化部署：所有组件以 Docker 容器运行在你自己的环境里，数据不出内网。本页提供基于 Docker Compose 的一体化部署方法。 ## 前置条件 **硬件**（最低）：4 核 CPU、16G 内存、100G 硬盘，x86 架构。 **软件**：Linux 服务器 + [Docker](https://docs.docker.com/engine/install/) + [Docker Compose](https://docs.docker.com/compose/install/) **v2.23.1+**（部署用到 `configs.content` 内联特性）。 **网络**：部署机器需放行以下地址的 HTTPS（443）出站访问： | 地址 | 用途 | | ------------------------------------- | ------------------------- | | `registry.cn-shanghai.aliyuncs.com` | 拉取镜像 | | `dockerauth.cn-hangzhou.aliyuncs.com` | 镜像鉴权 | | `aiproxy.asktable.com` | AI 模型服务（用 AskTable 托管模型时） | | `lf.asktable.com` | AI 调用追踪 | 完全离线部署：预先把镜像导入内网，并在 [配置大模型](/deploy/models) 时选「自定义」接入内网模型，即可不依赖外网。 ## docker-compose.yaml 新建一个目录，把下面的内容存为 `docker-compose.yaml`。每个服务的作用见行内注释；后端服务之间通过 Compose 内部网络通信，只有 `asktable` 对外暴露端口。海外服务器把镜像换成注释里的 Docker Hub 版本（`datamini/...`）。 ```yaml docker-compose.yaml theme={null} services: # 主服务：后端 API + 前端 + 内置 MCP（对外暴露的唯一服务） asktable: image: registry.cn-shanghai.aliyuncs.com/datamini/asktable-all-in-one:latest # 中国大陆；海外用 datamini/asktable-all-in-one:latest container_name: asktable depends_on: - asktable-pg - asktable-redis - asktable-atbox ports: - "8000:80" privileged: true environment: TZ: Asia/Shanghai AT_REGION: cn # cn 或 global；部署后保持不变 DATABASE_HOST: asktable-pg DATABASE_PORT: 5432 DATABASE_USER: asktable DATABASE_PASSWORD: asktable # 【建议修改】 DATABASE_DB: asktable REDIS_URL: redis://asktable-redis:6379 ATBOX_URL: http://asktable-atbox:5300 # Workbook 独立数据库：同实例同角色，独立 database（PG 无跨库查询 → 硬隔离） WORKBOOK_PG_DSN: postgresql://asktable:asktable@asktable-pg:5432/asktable_workbook volumes: - ./asktable_data:/asktable # PostgreSQL 17（pgvector）：主数据库（元数据、配置、字段向量） asktable-pg: image: registry.cn-shanghai.aliyuncs.com/dminfra/pgvector:pg17 container_name: asktable-pg restart: unless-stopped command: ["postgres", "-c", "max_connections=100"] environment: POSTGRES_USER: asktable POSTGRES_PASSWORD: asktable # 【建议修改】与 DATABASE_PASSWORD 保持一致 POSTGRES_DB: asktable volumes: - ./postgres_data:/var/lib/postgresql/data configs: # 仅在数据卷为空的全新部署首次执行一次，建 workbook 独立库 - source: workbook-initdb target: /docker-entrypoint-initdb.d/01-create-workbook-db.sql # Redis 7.4：任务队列 asktable-redis: image: registry.cn-shanghai.aliyuncs.com/dminfra/redis:7.4.4 container_name: asktable-redis restart: unless-stopped command: redis-server --appendonly yes volumes: - ./redis_data:/data # Python 沙箱：隔离执行智能体生成的不可信 Python。 # 下面标「安全」的是沙箱本体，请勿删改；标「可调」的资源上限可按机器调整。 asktable-atbox: image: registry.cn-shanghai.aliyuncs.com/datamini/asktable-atbox:latest # 中国大陆；海外用 datamini/asktable-atbox:latest container_name: asktable-atbox restart: unless-stopped environment: TZ: Asia/Shanghai ATBOX_MAX_WORKERS: 8 # 可调：并发 worker 数 ATBOX_DEFAULT_TIMEOUT: 30s # 可调：默认执行超时 ATBOX_MAX_TIMEOUT: 120s # 可调：最大执行超时 ATBOX_ENABLE_NETWORK: "0" # 安全：沙箱内禁用网络 # 安全：只读 rootfs + 临时可写区（/var/atbox/root/tmp 是 chroot 工作目录），两者配套，勿删 read_only: true tmpfs: - /var/atbox/root/tmp:rw,noexec,nosuid,nodev,mode=1777,size=512m - /tmp:rw,noexec,nosuid,nodev,mode=1777,size=64m # 安全：丢弃全部 capability，只加回 chroot + 降 UID 所需的最小集，勿改 cap_drop: - ALL cap_add: - CHOWN - DAC_OVERRIDE - SETUID - SETGID - SYS_CHROOT security_opt: - no-new-privileges:true # 安全：禁止提权 pids_limit: 128 # 可调：进程数上限（防 fork 炸弹） mem_limit: 1g # 可调：内存上限 cpus: 1.0 # 可调：CPU 上限 configs: # 内联建库 SQL，需 Docker Compose v2.23.1+（configs.content 支持） workbook-initdb: content: | CREATE DATABASE asktable_workbook; ``` 生产部署前务必改掉标了 **【建议修改】** 的默认密钥：`DATABASE_PASSWORD`（与 `POSTGRES_PASSWORD` 一致）。 要让团队在飞书群里问数，还需额外加一个飞书网关容器，见 [飞书网关](/deploy/feishu-gateway)。 ## 启动与初始化 在 `docker-compose.yaml` 所在目录执行： ```bash theme={null} docker compose up -d ``` 首次启动会自动初始化数据库（含 Workbook 独立库）。 浏览器打开 `http://<你的服务器地址>:8000/`。 按向导填写组织名称、创建管理员账号，并配置大模型（模型组），然后即可开始使用。系统会创建唯一的 default org，首个管理员是它的 Owner。 ## 访问地址 | 入口 | 地址 | | ------ | -------------------------------- | | 控制台 UI | `http://<服务器>:8000/` | | API 文档 | `http://<服务器>:8000/api/v1/redoc` | | MCP 服务 | `http://<服务器>:8000/mcp/` | ## 配置大模型 AskTable 不绑定特定模型，需要你配置一个大模型才能问数。首次启动向导会引导你完成，详见 [配置大模型](/deploy/models)。 ## 运维与连接容量 内置 PostgreSQL 的连接上限为 `100`，默认连接池适合常见的单机部署，通常无需调整。只有增加 Web 或 Worker 进程，或反复出现 `DATABASE_BUSY` 时，才需要查看 [运维与容量规划](/deploy/operations)。 ## 启用 Workbook Workbook 是内置的可写数据集，数据存在独立的 `asktable_workbook` 库，与主库硬隔离。上面的 compose 已配好 `WORKBOOK_PG_DSN` 并内联了建库 SQL： * **全新部署**：首次启动自动建库，无需操作。 * **已有部署升级**：数据卷已初始化、建库脚本不再执行，需手动建库一次： ```bash theme={null} docker compose exec asktable-pg psql -U asktable -d asktable -c "CREATE DATABASE asktable_workbook;" docker compose up -d ``` ## 版本升级 ```bash theme={null} docker compose pull docker compose down docker compose up -d ``` **从旧版升级**（移除 Qdrant、切换 pgvector 镜像、处理 collation 版本警告、重建 Embedding）见 [迁移](/deploy/migration)。 ## 卸载 ```bash theme={null} docker compose down rm -rf asktable_data postgres_data redis_data ``` 删除数据卷会清空所有数据，不可恢复。请先备份。 ## 后续步骤 * [配置大模型](/deploy/models) — 接入你自己的或托管的大模型 * [运维与容量规划](/deploy/operations) — 数据库连接池、进程并发与故障排查 * [飞书网关](/deploy/feishu-gateway) — 让团队在飞书群里问数 * [AI 搜索（值索引）](/deploy/ai-search) — 用简称提问也能命中完整值（可选，需 aisearch） * [进阶配置](/deploy/advanced) — 子路径部署、白标定制 * [商业授权](/deploy/license) — 试用限制与企业许可证 * [连接数据源](/concepts/data/connect) — 把数据接进来 # 飞书网关 Source: https://docs.asktable.com/deploy/feishu-gateway 飞书网关是私有部署里的可选组件，负责飞书 IM 的长连接。本页说明它的作用和如何在 compose 里启用。 飞书网关（`asktable-feishu-gateway`）是私有部署里的**可选组件**，只有当你要让团队在飞书群里 `@bot` 问数时才需要它。它通过 Redis 与 AskTable 后端通信，维持飞书 IM 的 WebSocket 长连接。 不接飞书的话，不用加这个容器。 ## 在 compose 里启用 在 [私有部署](/deploy/docker) 的 `docker-compose.yaml` 里加上这个服务： ```yaml theme={null} services: # 飞书网关（可选）：接入飞书 IM 时才需要 asktable-feishu-gateway: image: registry.cn-shanghai.aliyuncs.com/datamini/asktable-feishu-gateway:latest # 中国大陆；海外用 datamini/asktable-feishu-gateway:latest container_name: asktable-feishu-gateway restart: unless-stopped depends_on: - asktable-redis environment: TZ: Asia/Shanghai REDIS_URL: redis://asktable-redis:6379 ``` 它和主服务共用同一个 `asktable-redis`，无需额外暴露端口。改完执行 `docker compose up -d` 生效。 ## 下一步 容器起好后，飞书应用的创建、凭证配置、把机器人加进群等步骤，见 [在飞书中连接数据智能体](/how-to/connect-feishu)。 # 商业授权 Source: https://docs.asktable.com/deploy/license 私有部署的试用限制，以及如何获取并激活企业许可证。 AskTable 私有部署默认以**试用版**运行。要解除限制、用于生产，需要一份**企业许可证**。 ## 试用限制 未激活许可证时，私有部署有以下限制： * 最多 3 个用户 * 不支持画卷（Canvas）分析 企业许可证激活后，这些限制即解除。 ## 获取与激活 在 [AskTable 云控制台](https://cloud.asktable.com) 购买，或联系我们，拿到一段激活码。 使用系统管理员账号登录私有部署，从左下角个人菜单进入 **个人资料**，再从个人设置侧栏的 **组织** 分组打开 **组织信息**，在 **企业版** 区域填入激活码。普通用户不能激活或更新许可证。 获得授权后，可以使用 [进阶配置](/deploy/advanced)（子路径部署、白标定制等）。 # 迁移 Source: https://docs.asktable.com/deploy/migration 私有部署的版本迁移：常规升级，以及按版本号列出需要额外手动操作的迁移（如 v4.1.x → v4.2.x 的 Qdrant→pgvector）。 ## 常规升级 ```bash theme={null} docker compose pull && docker compose down && docker compose up -d ``` 启动时后端自动跑数据库迁移。下面按版本号列出需要**额外手动操作**的迁移——只做你跨过的版本。 ## 升级到 Organization 版本 这个版本把全部用户和项目放入唯一的 **default org**。首个 SYS\_ADMIN 成为组织 Owner，其他用户成为 Member；原公开/私密项目会映射为组织内公开/私密类别。现有项目、API Key、对话和 Dashboard 保留原 ID 与内容。 升级前必须备份 PostgreSQL 数据库和 `asktable_data`。如果当前实例没有 SYS\_ADMIN，迁移会主动失败，不会任意选择 Owner；请先在旧版本中恢复一个系统管理员。 ```bash theme={null} docker compose exec -T asktable-pg pg_dump -U asktable -Fc asktable > asktable-before-organization.dump docker compose down ``` 在 `asktable` 的环境变量中设置 `AT_REGION: cn` 或 `AT_REGION: global`。默认是 `cn`；它是部署级静态配置，后续变更需要身份数据迁移。Local 登录身份始终以邮箱为主，不因 Region 改变。 Google、GitHub、微信、邮箱登录、SMTP 与 SMS 不再从系统设置或数据库读取，旧的强制手机号开关也会删除。启动新版本前，把仍需使用的配置写入环境变量；OAuth 的 ID 与 Secret、SMS 的 URL 与 Key 必须分别成对填写。国内云生产必须完整配置微信与 SMS。变量清单与示例见 [部署认证配置](/deploy/authentication)。 企业微信/WPS 会迁入 default org，升级后在 **个人设置 → 组织 → 登录集成** 中维护。迁移会删除旧认证配置键，回滚依赖本步骤之前的数据库备份。 ```bash theme={null} docker compose pull docker compose up -d ``` 后端会先执行 Organization 数据库迁移，再启动应用。迁移失败时不要反复重启或跳过迁移，应保留日志并从备份恢复。 使用原管理员登录，确认组织名称、成员、项目、API Key、对话和 Dashboard 正常；每个项目应只有一名项目负责人，原 `is_public` 值应正确映射为公开或私密项目，且不再出现 VIEWER 或匿名项目访问。 全新私有部署会在 setup 向导中要求填写组织名称。升级实例使用迁移生成的 default org 名称，Owner 可以在个人设置的组织设置中修改。升级后，项目和用户在个人设置的“组织”分组下治理；系统设置不再提供全局项目或用户入口。 Cloud 的组织订阅、余额与订单迁移需要在生产快照副本上先跑预检和对账断言，并在暂停 web/worker 的发布窗口一次完成。若预检输出 `cloud_legacy_enterprise_credentials` 或 `cloud_legacy_enterprise_config`，必须停止升级、导出相关数据并交由迁移负责人决定归属；migration 不会自动删除这些 Cloud 数据或猜测目标组织。值为空的历史企微/WPS 配置占位键不计入该 blocker。这不是普通私有部署的操作路径。 ## v4.1.x → v4.2.x（Qdrant → pgvector） 此区间字段向量从独立 Qdrant 改存主库 pgvector。从 v4.1.x 升级到 v4.2.x 需要： 官方 `postgres` 镜像不带 pgvector 扩展，必须换（扩展由迁移脚本自动安装）： ```yaml docker-compose.yaml theme={null} asktable-pg: image: registry.cn-shanghai.aliyuncs.com/dminfra/pgvector:pg17 # 原来是 postgres:17 ``` 对照 [私有部署](/deploy/docker) 最新 compose，删除 `asktable_vdb` 服务、`VDB_ADDRESS`/`VDB_API_KEY` 环境变量、`qdrant_storage`/`qdrant_snapshots` 卷。 ```bash theme={null} docker compose pull && docker compose down && docker compose up -d ``` 自动迁移并安装 pgvector 扩展。缺 `asktable_workbook` 库时按 [私有部署](/deploy/docker) 补建。 老数据源向量为空，进每个数据源页点 **重建 Embedding** 回填。 ### collation 版本警告 只有**换了 PostgreSQL 镜像、底层 glibc 版本变化**时才会遇到，判据是启动日志出现 `collation version mismatch`。 * 在原有 PostgreSQL 上自己装 pgvector 扩展、没换镜像 → 不触发，跳过本节。 * 把旧镜像（如早期部署用的 postgres 镜像）换成 pgvector 镜像、且复用旧 `postgres_data` 卷 → 触发，按下面处理。 别只按提示刷版本号。glibc 版本不同会改变文本排序规则，旧文本索引与数据对不上，查询会静默漏行。必须先重建索引，再刷版本号。 ```bash theme={null} docker compose exec asktable-pg psql -U asktable -d asktable -c "REINDEX DATABASE asktable;" docker compose exec asktable-pg psql -U asktable -d asktable -c "ALTER DATABASE asktable REFRESH COLLATION VERSION;" docker compose exec asktable-pg psql -U asktable -d postgres -c "ALTER DATABASE template1 REFRESH COLLATION VERSION;" ``` 启用了 Workbook 就对 `asktable_workbook` 库做同样两步。数据可弃时更省事：`docker compose down -v` 删卷重建（**生产勿用，会清空数据**）。 # 配置大模型 Source: https://docs.asktable.com/deploy/models AskTable 支持任意 OpenAI 兼容或 Anthropic 协议的大模型。控制台向导会引导你配置，本页讲背景和如何获取模型算力。 AskTable 不绑定特定大模型。首次启动时，控制台的**设置向导**会一步步引导你完成模型配置，你只需准备好一个模型的接入信息。本页讲清楚选型背景，以及如何获取模型算力。 ## 支持哪些模型 只要能通过下面两种协议之一访问，就能接入： * **OpenAI 兼容** —— OpenAI GPT、阿里云百炼（通义千问 Qwen）、DeepSeek，以及任何 OpenAI 兼容端点。 * **Anthropic** —— Claude 系列。 ## 对模型的要求 AskTable 的智能体靠**调用工具**来查数、跑 Python、画图，所以模型**必须支持函数调用 / 工具调用（function calling / tool use）**。 模型能力以 **deepseek-v4-pro** 为基准，越强越稳；上下文窗口也是越大越好。 ## 获取模型算力 不想自己准备大模型 key，可以直接用 AskTable 提供的托管算力：在 [AskTable 云控制台 → 私有部署](https://cloud.asktable.com/u/settings/private-deploy) 申请一个**模型算力 API Key**，在向导里填入即可，省去逐家对接。 要接自己的或内网的模型，在向导里选自定义，填模型的接入地址、key 和模型名。 ## 后续步骤 * [私有部署（Docker）](/deploy/docker) — 部署 AskTable 本体 * [连接数据源](/concepts/data/connect) — 把数据接进来 # 运维与容量规划 Source: https://docs.asktable.com/deploy/operations 了解 AskTable 默认数据库连接容量，并排查 DATABASE_BUSY。 默认配置适合常见的单机部署。没有反复出现 `DATABASE_BUSY`，也没有增加 Web 或 Worker 进程时，无需修改连接池。 ## 默认连接容量 | 项目 | 默认值 | | ------------------------------- | -------------------------: | | Web 进程 | `1` | | 每个 Web 进程的主库连接上限 | `20`（连接池 `10` + 临时连接 `10`） | | Worker 进程 | `1` | | 每个 Worker 进程的主库连接上限 | `10`（连接池 `5` + 临时连接 `5`） | | 每个进程的 Workbook 连接上限 | `10` | | 内置 PostgreSQL `max_connections` | `100` | 默认启用 Workbook 时，应用的保守连接峰值是 `51`： ```text theme={null} Web 20 + Worker 10 + Workbook 20 + LISTEN/NOTIFY 1 = 51 ``` PostgreSQL 上限 `100` 已包含足够余量。`POOL_SIZE` 只是连接池保留的连接数，不是连接上限；连接上限还要加上 `MAX_OVERFLOW`。 ## 遇到 DATABASE\_BUSY `DATABASE_BUSY` 表示 AskTable 暂时没有拿到数据库连接，或者 PostgreSQL 已达到连接上限。页面会自动重试，仍未恢复时可以手动重试。 如果错误反复出现： 1. 查看日志，确认来自 Web 请求还是后台刷新。 2. 后台刷新繁忙时，先降低 `AT_WORKER_MAX_JOBS`。 3. PostgreSQL 已报连接数耗尽时，不要继续增大连接池。 4. 只有确认 PostgreSQL 仍有余量、且本地连接池等待超时时，才调大对应的 Web 或 Worker 池。 ## 增加进程时 每增加一个 Web 进程，会增加一套 Web 主库池、最多一套 Workbook 池和一个 `LISTEN/NOTIFY` 连接。每增加一个 Worker 进程，会增加一套 Worker 主库池和最多一套 Workbook 池。 调整顺序建议是：缩短事务、降低后台并发、调整对应角色的连接池，最后才提高 PostgreSQL 上限。始终为迁移和人工排障保留至少 10 个连接。 所有配置都是静态环境变量，修改后需要重启对应进程。 | 配置 | 默认值 | 说明 | | --------------------------- | ----------: | -------------------------- | | `AT_SERVER_WORKERS` | `1` | Web 进程数；命令行 `--workers` 优先 | | `AT_WEB_DB_POOL_SIZE` | `10` | 每个 Web 进程保留的主库连接数 | | `AT_WEB_DB_MAX_OVERFLOW` | `10` | Web 池满时可临时增加的连接数 | | `AT_WORKER_NUM_PROCS` | `1` | Worker 进程数 | | `AT_WORKER_MAX_JOBS` | `10` | 每个 Worker 同时执行的最大任务数 | | `AT_WORKER_DB_POOL_SIZE` | `5` | 每个 Worker 进程保留的主库连接数 | | `AT_WORKER_DB_MAX_OVERFLOW` | `5` | Worker 池满时可临时增加的连接数 | | `AT_DB_POOL_TIMEOUT` | `30` | 等待主库连接的最长秒数 | | `AT_DB_POOL_RECYCLE` | `300` | 主库连接回收秒数 | | `WORKBOOK_PG_DSN` | 本地主库中的独立数据库 | 非空时启用；显式设为空可关闭 | | `AT_WORKBOOK_POOL_MIN` | `1` | 每个进程保留的最少 Workbook 连接数 | | `AT_WORKBOOK_POOL_MAX` | `10` | 每个进程最多使用的 Workbook 连接数 | Web 和 Worker 的池容量分别配置；等待和回收时间由两类进程共用。所有池参数必须为非负数，且 Workbook 必须满足 `0 <= MIN <= MAX`。 `B` 表示启用 Workbook 时的 `AT_WORKBOOK_POOL_MAX`，未启用时为 `0`。 ```text theme={null} 应用连接上限 = AT_SERVER_WORKERS × (AT_WEB_DB_POOL_SIZE + AT_WEB_DB_MAX_OVERFLOW + B + 1) + AT_WORKER_NUM_PROCS × (AT_WORKER_DB_POOL_SIZE + AT_WORKER_DB_MAX_OVERFLOW + B) ``` 应用连接上限加至少 10 个运维连接后，必须小于 PostgreSQL 可供普通用户使用的连接数。后者等于 `max_connections` 减去 `reserved_connections` 和 `superuser_reserved_connections`。 查看 PostgreSQL 上限： ```sql theme={null} SHOW max_connections; SHOW reserved_connections; SHOW superuser_reserved_connections; ``` 查看连接来源和长事务： ```sql theme={null} SELECT application_name, state, count(*) AS connections, max(now() - xact_start) AS longest_transaction FROM pg_stat_activity WHERE datname IN ('asktable', 'asktable_workbook') GROUP BY application_name, state ORDER BY connections DESC; ``` 查看容器日志： ```bash theme={null} docker compose logs --since=30m asktable | grep -E 'DATABASE_BUSY|creating postgresql pool|refresh_table_task' docker compose logs --since=30m asktable-pg ``` 使用外部 PostgreSQL 时，以数据库服务商提供的实际连接上限为准，AskTable 不会自动修改它。 # 快速入门 Source: https://docs.asktable.com/get-started/quickstart 从注册账号到与数据对话，5 分钟体验 AskTable 核心流程。 本指南带你完成最关键的 5 步，从零开始体验 AskTable。 访问 [asktable.com](https://asktable.com) 注册账号，登录进入控制台。 在控制台左侧选择"数据源"，添加你的数据库（MySQL、PostgreSQL、TiDB 等均支持）。详见[连接数据源](/concepts/data/connect)。 AskTable 会自动解析表结构。等待状态变为"已就绪"。 进入"对话"页面，用自然语言提问，例如"上个月销售额最高的 5 个产品是什么"。 AskTable 会返回数据表、图表，可一键分享或加入数据看板。 ## 下一步 * 连数据源遇到问题？查看[连接数据源](/concepts/data/connect) # 通过 CLI 使用 AskTable Source: https://docs.asktable.com/how-to/cli 安装 AskTable CLI 并导出技能文件，让 AI 编程助手替你驱动 AskTable。 AskTable CLI 是官方命令行工具，发布为 npm 包 `@datamini/asktable-cli`，命令名 `asktable`。能在终端里管理数据源、问数、配置权限。 ## 安装 ```bash theme={null} npm i -g @datamini/asktable-cli ``` 装好后即可用 `asktable` 命令。需要 Node.js 18+。 ## 获取技能 CLI 自带一份 **Agent Skill**——一段教 AI 编程助手（如 Claude Code）怎么用 `asktable` 命令的说明文件，认证、问数、各命令组的用法都在里面。导出： ```bash theme={null} asktable get-skill ``` 把导出的文件放进编程助手的 skills 目录，助手就能用自然语言驱动 AskTable CLI（建数据源、问数、配权限等）。想自己上手，运行 `asktable --help`。 这里的「Skill」是给 AI **编程助手**用的 CLI 使用说明，和 AskTable 里挂在智能体上的 [技能](/concepts/agent/skill)（分析方法）是两回事，别混淆。 ## 后续步骤 * [MCP](/how-to/mcp) — 另一种把 AskTable 接给 AI agent 的方式 * [连接数据源](/concepts/data/connect) — 了解数据源概念 # 在扣子中集成和查询数据 Source: https://docs.asktable.com/how-to/connect-coze 把 AskTable 作为插件接入扣子的智能体、工作流或对话流，让扣子机器人用一句话查 Excel 和数据库。 扣子（Coze）是字节跳动的智能体搭建平台。把 AskTable 的官方插件加到扣子里，你的扣子机器人就能用自然语言查 AskTable 上的数据——比如「张三考了多少分」。 ## 官方插件 在扣子插件商店搜索 **AskTable**，选 [一句话查 Excel 或数据库](https://www.coze.cn/store/plugin/7407079384349343784)。它用来查询你已经在 AskTable 里连好的数据源（Excel、数据库都行）。 ## 前置条件 在 AskTable 控制台准备好两样东西： 1. **数据源**：已经连好，并记下它的 ID（形如 `ds_xxxxxxxx`）。还没连见 [连接数据源](/concepts/data/connect)。 2. **API-Key**：在 **设置 → API-Key** 新建一个 **asker** 类型的 key（问数用，权限低），完整值形如 `ASKER_xxxxxxxx`。 扣子插件用 **asker**（低权限）key，不要用 admin key。asker 只能问数，万一泄露风险也小。 ## 在智能体中使用 打开 [扣子](https://www.coze.cn)，创建一个智能体，填好基本信息。 在智能体编辑页找到「插件」区，点 **+**，搜索 **AskTable**，选「一句话查 Excel 或数据库」添加。 在智能体的「变量」里建两个： | 变量名 | 值 | | ---------- | ------------------------------------------- | | `at_auth` | `Bearer ASKER_xxxxxxxx`（注意 `Bearer ` 前缀加空格） | | `at_ds_id` | `ds_xxxxxxxx`（你的数据源 ID） | 在插件的参数配置里绑定： * `Authorization` → 变量 `at_auth` * `datasource_ids` 是数组，添加一个数组项，值绑定变量 `at_ds_id`（或直接填数据源 ID）。要一次查多个数据源，就添加多个数组项。 用预览功能问一句（比如「张三考了多少分」），确认能正确返回结果。 ## 在工作流 / 对话流中使用 流程一样：在工作流或对话流里添加 AskTable 插件节点，同样用 `at_auth`、`at_ds_id` 两个变量配置参数，`Authorization` 保持 `Bearer ASKER_xxxxxxxx` 格式，`datasource_ids` 数组项填数据源 ID 即可。 ## 后续步骤 * [连接数据源](/concepts/data/connect) — 先把数据接进 AskTable * [MCP](/how-to/mcp) — 想让其它 AI agent 接入 AskTable，可以用 MCP # 在飞书中连接数据智能体 Source: https://docs.asktable.com/how-to/connect-feishu 从飞书开放平台建应用、配置权限,到 AskTable 中填入凭证,把数据智能体接入飞书群,完成端到端的群内问数。 把一个智能体接到飞书群,用户就能在群里 `@bot` 用自然语言查数据。整个流程分两边:**飞书开放平台**(建应用、给权限)和 **AskTable**(填凭证、加进群)。 ## 前置条件 * 飞书企业有 **管理员权限**(自建应用需要管理员审批后才能用) * 已经在 AskTable 中创建好一个智能体,并且配好了数据源和技能。如果还没有,先去 **数据智能体** 列表新建一个 ## 1. 在飞书开放平台创建自建应用 进入 [open.feishu.cn](https://open.feishu.cn) → **开发者后台** → **创建企业自建应用**。 填好应用名称、图标、描述后保存。进入应用后,在 **凭证与基础信息** 页面找到下面两个值,先记下来: | 字段 | 说明 | | -------------- | ---------------------- | | **App ID** | 形如 `cli_xxxxxxxx`,公开标识 | | **App Secret** | 应用密钥,只显示一次,泄露要立刻重置 | ## 2. 启用机器人能力 在应用后台左侧 **添加应用能力** → 开启 **机器人**。机器人能力是飞书群里能 `@` 到你的应用的前提。 ## 3. 配置事件订阅 进入 **事件与回调** → **事件配置**。AskTable 采用 **长连接** 模式接收事件,**不需要** 在飞书后台填 Webhook URL,飞书会通过 WebSocket 把消息推到 AskTable 内置的网关。 需要订阅的事件: * **接收消息 v2.0** (`im.message.receive_v1`) —— 让机器人收到群里和私聊里的消息 ## 4. 配置 API 权限 在 **权限管理** → **API 权限** 中开启下面两个权限,这是「能在群里问数」的最小集: | 权限 | 作用 | | ---------------------------------- | ---------------- | | `im:message` | 获取与发送单聊、群组消息 | | `im:message.group_at_msg:readonly` | 获取群组中用户 @机器人 的消息 | **要做权限管控?** 如果还想按人 / 按部门控制不同用户能问到的数据,需要再开通 3 个通讯录权限。具体见 [如何在飞书配置人员和角色权限](/how-to/feishu-permissions)。 ## 5. 发布并审核应用 在 **版本管理与发布** 中创建一个版本,提交审核。飞书管理员审核通过后,应用才会在企业内生效。 ## 6. 在 AskTable 中填入凭证 回到 AskTable,进入对应数据智能体的详情页,切到顶部的 **频道** Tab,在 **频道** 下拉里选 **飞书**(下拉是「不启用 / 飞书 / Slack」三选一)。弹出的凭证对话框里填: | 字段 | 必填 | 说明 | | ---------------------- | -- | --------------------------------------------- | | **App ID** | 是 | 第 1 步记下的值 | | **App Secret** | 是 | 第 1 步记下的值 | | **Encrypt Key** | 否 | 仅当你在飞书后台的「事件与回调 > 加密策略」开启了消息加密时才填,且要和飞书后台保持一致 | | **Verification Token** | 否 | 同上,通常不用 | 点 **保存**,飞书即成为该智能体当前生效的平台。保存后在下方 **通用配置** 里还能调两个开关: | 开关 | 飞书默认 | 说明 | | ---------- | ---- | -------------------------------------------------- | | **在话题中回复** | 关 | 关闭时机器人直接回在群里;开启则在提问消息下开话题回复,话题内的追问自动续同一段对话、问答归拢不刷屏 | | **深度推理** | 关 | 开启后模型推理更长时间,适合复杂问题 | ## 7. 验证连接 保存后,**频道** 卡片里会显示连接状态: * 绿点 **已连接** → 凭证正确,WebSocket 已建立 * 黄点 **连接中** → 正在握手,等几秒 * 红点 **错误** → 凭证错误或飞书侧拒绝了连接,根据脱敏错误摘要核对 App ID / Secret 和应用是否已发布 状态每 5 秒自动更新。**刷新** 只会重新读取状态,不会主动重连;掉线重连由飞书 SDK 负责。绿点表示凭证有效且当前长连接存活,不代表 Agent 处理和回复投递一定成功。 发送一条测试消息后,查看卡片里的 **最近消息**。主界面会按「接收消息 → 处理中 → 已回复」展示进度;没有最新消息通常是事件订阅、应用权限或机器人入群有问题。点击「详情」后,处理失败表示 Agent 任务异常,回复失败表示飞书投递异常。 **频道是否启用** 只要 **频道** 下拉选的是 **飞书**,即便没人在群里说话,连接状态也应该长期保持「已连接」。如果出现频繁掉线,通常是 App Secret 被你在飞书后台重置过但 AskTable 这边没更新。 ## 8. 把机器人加进飞书群 回到飞书,在目标群里: 1. 输入 `@`,选择 **添加机器人** 2. 搜索刚才发布的应用名,选中并确认 3. 在群里 `@刚加进来的机器人 你的问题`,例如「上个月销售额最高的 5 个产品是什么」 机器人会回复一张消息卡片,展示分析结果。 ## 9. 后续步骤 * 想控制谁能问、谁能看到哪些数据 → [如何在飞书配置人员和角色权限](/how-to/feishu-permissions) * 还没接好数据源 → [连接数据源](/concepts/data/connect) * 想给字段加业务说明、提高 AI 准确度 → [表、字段备注](/concepts/data/annotations) # 连接企业微信 Source: https://docs.asktable.com/how-to/connect-wecom 创建企业微信自建应用，取得 CorpID、AgentID 和 Secret，并在 AskTable 启用登录与成员导入。 连接后，企业成员可以从组织专属链接登录 AskTable。AskTable 只会导入自建应用可见范围内的成员。 ## 前置条件 * 你是 AskTable 当前组织的 Owner 或 Admin； * 你可以登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame) 并创建自建应用； * AskTable 的登录地址可以被成员浏览器访问。私有部署建议使用公开可访问的 HTTPS 域名。 ## 1. 创建自建应用 在企业微信管理后台进入 **应用管理 → 自建 → 创建应用**，填写应用名称、介绍和图标。 创建后，在应用详情页完成两项设置： 1. 在 **可见范围** 中选择允许登录 AskTable 的部门和成员； 2. 保持应用启用，并设置至少一名应用负责人。 企业微信自建应用详情页中的 AgentID、Secret、可见范围和应用主页 AskTable 查询导入候选时以这里的可见范围为准。范围过小会导致目标成员不可选；范围过大会显示更多候选，但不会自动导入。 ## 2. 取得三个凭据 准备以下信息： | AskTable 字段 | 企业微信中的位置 | | ----------- | ------------------------ | | **CorpID** | **我的企业 → 企业信息 → 企业 ID** | | **AgentID** | 自建应用详情页的 **AgentId** | | **Secret** | 自建应用详情页的 **Secret → 查看** | Secret 是敏感凭据，只应保存在 AskTable 配置中。若在企业微信重置 Secret，必须回到 AskTable 更新配置。 ## 3. 在 AskTable 启用集成 进入 **个人设置 → 组织 → 登录集成 → 企业微信**，阅读介绍后点击 **Enable**。在弹窗中填写 CorpID、AgentID 和 Secret，然后点击 **启用**。 Enable 只保存配置，不会立即验证凭据，也不会自动导入成员。保存成功后，页面下方的地址、导入和编辑操作才会启用。 ## 4. 配置应用主页和授权域名 启用后，在 AskTable 的 **登录地址** 区复制 **回调地址**。回到企业微信自建应用详情页，点击 **应用主页 → 设置**，选择 **网页**，把完整回调地址填入 **网页地址**。 企业微信设置工作台应用主页网页地址的弹窗 如果企业微信后台要求配置 **网页授权及 JS-SDK** 的可信域名或授权回调域，请使用 AskTable 回调地址中的域名，不要带协议和路径。例如回调地址是 `https://example.com/login/sso/wecom`，则域名填写 `example.com`。Cloud 地址还会附带 `?org_id=...`，但域名填写方式相同。 ## 5. 选择导入成员 回到 AskTable，点击 **导入成员**。在弹窗中搜索、筛选并勾选需要导入的人；页面会提示剩余名额，提交成功后显示新增和已存在人数。 * 新成员以 Member 角色加入组织； * 已存在成员的角色不会改变； * 上游删除成员不会自动停用 AskTable 成员； * 已停用的 AskTable 成员不会被同步操作自动恢复。 如需调整候选范围，先修改企业微信自建应用的 **可见范围**，再重新打开导入弹窗。 ## 6. 验证登录 1. 确认测试成员在应用可见范围内，并已成功导入； 2. 在企业微信工作台打开该自建应用，或在成员浏览器打开 AskTable 回调地址； 3. 完成企业微信授权后，确认进入正确的 AskTable 组织。 首次企业登录不会自动创建成员。测试成员必须已经同步，并且 AskTable 用户和组织成员状态都正常。 ## 排障 ### 候选查询或导入失败 * 核对 CorpID 和 Secret 是否来自同一个企业； * 确认 Secret 没有被重置； * 检查自建应用的可见范围是否包含目标部门或成员； * 检查企业微信后台是否限制了调用 API 的可信 IP；若已限制，需要加入 AskTable 部署的出口 IP。 ### 打开应用主页后无法授权 * 确认应用主页使用 AskTable 页面复制出的完整回调地址； * 确认可信域名与回调地址的域名一致； * 确认应用已启用，且测试成员在可见范围内； * Local 必须使用页面显示的无参地址；Cloud 地址中的 `org_id` 不能删除或修改。 ### 更换企业 CorpID 启用后不能直接修改。请先在详情页断开集成，再用新企业的凭据重新启用。断开不会删除已有用户、组织成员或项目数据。 更多身份范围和断开规则见 [企业集成登录](/concepts/organization/enterprise-login)。 # 连接 WPS Source: https://docs.asktable.com/how-to/connect-wps 创建 WPS 企业自建应用，取得 AppID 和 AppKey，并在 AskTable 启用登录与成员导入。 连接后，企业成员可以通过组织专属链接完成 WPS 授权并登录 AskTable。AskTable 按 WPS 应用的可见范围同步企业成员。 ## 前置条件 * 你是 AskTable 当前组织的 Owner 或 Admin； * 你有权限在 WPS 开放平台创建和管理当前企业的自建应用； * AskTable 的回调地址可以被成员浏览器访问。私有部署建议使用公开可访问的 HTTPS 域名。 ## 1. 创建企业自建应用 登录 [WPS 开放平台](https://open.wps.cn)，进入开发者后台并创建企业自建应用。填写应用名称、简介和图标，然后进入应用详情页。 在详情页找到应用的 **AppID** 和 **SecretKey/AppKey**。不同版本的 WPS 控制台可能把密钥显示为 SecretKey 或 AppKey，AskTable 中统一称为 AppKey。 WPS 企业自建应用详情页中的 AppID、SecretKey 和可见范围 AppKey 是敏感凭据。若在 WPS 开放平台重置密钥，原密钥会失效，必须回到 AskTable 更新配置。 ## 2. 配置权限和可见范围 在应用详情页完成以下设置： 1. 在 **可见范围** 中选择允许登录 AskTable 的部门和成员； 2. 在 **权限管理** 中申请读取用户基本信息、读取通讯录或应用可见范围所需的权限； 3. 按 WPS 控制台要求提交审批或上架，使应用对企业成员生效。 权限名称会随 WPS 控制台版本变化。原则是：登录需要读取当前授权用户的基本信息，成员导入需要读取企业通讯录和应用可见范围。 ## 3. 在 AskTable 启用集成 进入 **个人设置 → 组织 → 登录集成 → WPS 协作**，阅读介绍后点击 **Enable**。在弹窗中填写 AppID 和 AppKey，然后点击 **启用**。 Enable 只保存配置，不会立即验证凭据，也不会自动导入成员。保存成功后，页面下方的地址、导入和编辑操作才会启用。 ## 4. 配置授权回调地址 启用后，在 AskTable 的 **登录地址** 区复制 **回调地址**。回到 WPS 应用详情页，进入 **安全设置**，把完整地址加入授权回调地址配置。 WPS 应用详情页中的安全设置入口 回调地址必须与页面显示完整一致，包括协议、域名和路径。Local 地址不带查询参数；Cloud 地址还包括 `org_id`，不能删除或修改。不要在末尾额外添加 `/`。 如果安全设置启用了 IP 白名单，还需要加入 AskTable 部署的出口 IP；否则候选查询或成员导入可能因 WPS 拒绝接口调用而失败。 ## 5. 选择导入成员 回到 AskTable，点击 **导入成员**。在弹窗中搜索、筛选并勾选需要导入的人；页面会提示剩余名额，提交成功后显示新增和已存在人数。 * 新成员以 Member 角色加入组织； * 已存在成员的角色不会改变； * 上游删除成员不会自动停用 AskTable 成员； * 已停用的 AskTable 成员不会被同步操作自动恢复。 如需调整候选范围，先修改 WPS 应用的 **可见范围**，再重新打开导入弹窗。 ## 6. 验证登录 1. 确认测试成员在应用可见范围内，并已成功导入； 2. 从 AskTable 页面复制 **回调地址**，在测试成员的浏览器中打开； 3. 完成 WPS 授权后，确认进入正确的 AskTable 组织。 首次企业登录不会自动创建成员。测试成员必须已经同步，并且 AskTable 用户和组织成员状态都正常。 ## 排障 ### 候选查询或导入失败 * 核对 AppID 和 AppKey 是否来自同一个应用； * 确认 AppKey 没有被重置； * 检查读取通讯录和应用可见范围的权限是否已经审批生效； * 检查目标部门或成员是否在应用可见范围内； * 若启用了 IP 白名单，确认 AskTable 部署的出口 IP 已加入。 ### 授权后无法返回 AskTable * 确认 WPS 安全设置中的回调地址与 AskTable 页面显示的地址逐字一致； * 确认应用已经审批或上架，并对测试成员可见； * Local 必须使用页面显示的无参地址；Cloud 地址中的 `org_id` 不能删除或修改。 ### 更换企业或应用 AppID 启用后不能直接修改。请先在详情页断开集成，再用新应用的凭据重新启用。断开不会删除已有用户、组织成员或项目数据。 更多身份范围和断开规则见 [企业集成登录](/concepts/organization/enterprise-login)。 # 配置渠道用户访问数据的权限 Source: https://docs.asktable.com/how-to/feishu-permissions 通过白名单和角色,控制飞书群里不同用户能问到哪些数据 —— 涵盖人员建档、角色分配、行级过滤的完整流程。 接通飞书后([如何连接智能体到飞书群组](/how-to/connect-feishu)),默认情况下群里任何人都可以问数。如果你需要按部门、按身份控制谁能看到哪些数据,就要用到 AskTable 的「白名单 + 角色」机制。 ## 权限模型概述 AskTable 把飞书用户和数据权限的关系拆成三层: ```text theme={null} 飞书 user_id ──绑定──> 人员 (Person) ──授权──> 数据智能体 + 角色 (Role) │ └──> 策略 (Policy) ──> 字段/行级规则 ``` * **人员(Person)** —— AskTable 内部的用户档案,可以一人对应多个外部渠道身份(飞书、未来的钉钉等) * **渠道绑定(Channel Binding)** —— 把飞书的 `user_id` 关联到一个 Person * **角色(Role)** —— 一组策略的打包,决定能看哪些数据范围 * **策略(Policy)** —— 实际的访问规则,包括允许/拒绝、字段级、行级过滤 数据智能体的每个渠道各有一个 **白名单** 开关(飞书、Slack 独立配置,互不影响): * **关闭** —— 任何能进群的飞书用户都能问数(适合内部共享数据) * **开启** —— 必须先在白名单里,否则消息会被拒绝,同时自动进入「待审批」列表 ## 1. 在飞书开放平台补开通讯录权限 要识别飞书用户身份(拿到 `user_id`、姓名、邮箱),必须先在飞书后台的 **权限管理** → **API 权限** 加开下面 3 个权限。这是在 [连接飞书](/how-to/connect-feishu) 那两个基础权限之上额外要补的: | 权限 | 作用 | | ----------------------------------- | ---------------------------- | | `contact:contact.base:readonly` | 获取通讯录基本信息 | | `contact:user.base:readonly` | 获取用户基本信息(姓名、邮箱、手机) | | `contact:user.employee_id:readonly` | 获取用户 `user_id` —— 白名单匹配的核心字段 | `contact:*` 权限属于「申请类」,需要企业管理员单独审批。审批通过前,飞书用户问数会一直被挡在白名单外,AskTable 也拿不到他们的姓名邮箱来建档。 开通后记得回到 **版本管理与发布**,**重新提交一个新版本** 并等管理员审批 —— 飞书的权限变更必须随版本发布才会生效。 ## 2. 开启数据智能体的白名单 进入数据智能体详情页的 **频道** Tab,在「人员权限」区域找到 **白名单** 开关。开关属于当前生效的渠道 —— 飞书和 Slack 各自独立控制,切换渠道时各自的开关状态保留: | 状态 | 含义 | | ------ | ---------------------- | | **关闭** | 任何能进群的飞书用户都可问数 | | **开启** | 仅在白名单内的人可以通过当前渠道访问此智能体 | 打开开关后,新的飞书用户首次问数会被拒绝,并在 AskTable 这边自动生成一条「待审批」记录。已授权人员列表也按当前渠道过滤 —— 只显示在该渠道有身份绑定的人。 ## 3. 处理待审批申请 进入 **数据访问控制** → **人员**,顶部有两个 Tab: * **已建档** —— 已经在 AskTable 中有档案的人员 * **待审批** —— 飞书用户首次问数自动出现在这里 每条待审批记录展示: | 字段 | 说明 | | ----------------- | ------------------------ | | **姓名 / 头像** | 从飞书拉取 | | **邮箱 / 手机** | 从飞书拉取,可能为空 | | **申请访问** | 这个用户想问哪个数据智能体 | | **最近申请 / 首次申请时间** | 同一个人多次申请会合并 | | **状态** | 未建档 / 已建档待授权 / 已通过 / 已拒绝 | 操作有三个: * **建档/关联** —— 走下一步,把飞书身份和 AskTable 人员档案绑起来 * **分配权限** —— 已建档但还没分配角色时用 * **拒绝** —— 永久拒绝这个申请,该用户后续问数会一直被挡 ## 4. 建档:新建人员或关联到已有人员 点 **建档/关联** 弹出对话框,先看顶部 **飞书账号信息**(姓名、`user_id`、邮箱、手机),然后选两种模式之一: * **新建人员档案** —— 创建一个全新的 Person,姓名/邮箱/手机会从飞书自动填好,可以再加备注 * **关联到已有人员** —— 按姓名/邮箱/手机搜索已有 Person,选中后会自动加上飞书绑定 飞书的 `user_id` 是自动绑定的,不需要你手填。一个 Person 可以同时绑多个飞书 `user_id`(比如同一个人在多个企业里)。 点 **建档** 完成。这一步只是把「这个飞书用户」和「这个 AskTable 人员」对上号,还没有赋予任何数据权限。 ## 5. 分配角色 建档完成后会接着弹出 **为「xxx」分配「yyy 智能体」的权限** 对话框,关键字段是 **角色**: | 选择 | 行为 | | -------------- | --------------------------------- | | **不选任何角色** | 全权 —— 用户能看到该智能体配置的全部数据范围,不做任何额外过滤 | | **选择一个已建好的角色** | 应用该角色绑定的所有策略(allow/deny、字段级、行级) | 如果选中的角色定义了 **必填变量**(比如 `dept_id`、`user_id`),对话框会展开 **角色变量** 字段,你需要给这个人填上对应值。这些值会在用户问数时拼到 SQL 的 WHERE 里,实现行级过滤(RLS)。 举个例子:角色 **部门数据** 绑定了一条策略「`orders` 表只能看 `dept_id = {{dept_id}}` 的行」,那么: * 给「张三」分配此角色时,**dept\_id** 填 `D001` * 张三在飞书里问「上月销售额」,生成的 SQL 会自动带上 `WHERE dept_id = 'D001'` * 李四的 `dept_id` 是 `D002`,问同一个问题看到的是完全不同的子集 点 **授权** 完成。这个人之后在飞书里问数就会按这个角色的规则放行。 ## 6. 创建可复用的角色 如果是第一次配,需要先去 **数据访问控制 → 角色 → 新建角色**: 1. **取名**,比如「部门数据」「销售经理」「外部访客」 2. 在 **应用策略** 区域 **添加策略** —— 没有合适的策略就先去 **数据访问控制 → 策略** 建一个 3. 保存 **策略(Policy)** 才是真正定义「能看哪些库/表/字段、能过滤哪些行」的地方,角色只是把若干策略打包。一个策略包含: * **权限方向** —— 允许 / 拒绝 * **数据源** —— 适用于哪些数据源 * **字段级规则** —— 按 schema / table / field 三层匹配模式控制可见字段 * **行级过滤** —— 在指定字段上加 WHERE 条件,支持引用变量 完整策略和角色的使用方式不在本文范围,先建好你需要的角色,再回到第 5 步分配。 ## 7. 常见场景示例 ### 场景 A:全员只读全部数据 最简单的情况,不开白名单,任何人进群都能问。适合企业内部知识共享。 ### 场景 B:按部门隔离 * 开启白名单 * 建一个「部门数据」角色,策略带行级过滤 `dept_id = {{dept_id}}` * 每次审批新人时,在「角色变量」里填好这个人的 `dept_id` ### 场景 C:外部访客只看部分数据 * 开启白名单 * 建一个「访客」角色,绑定一条「仅允许 `public` schema」的 allow 策略 * 外部用户首次问数 → 进入待审批 → 你审批时分配「访客」角色 * 内部员工分配其他更宽松的角色 ## 8. 撤销权限 两种方式: * **保留人员,移除单个智能体的访问** —— 进入人员详情页 → **已授权的数据智能体** 区域 → 找到对应智能体 → 点 **移除** * **彻底清除** —— 在人员详情页右下角的 **危险操作** 区域 **删除人员**。所有渠道绑定和已授权访问会一并清除,该用户在飞书里再问数会重新走「待审批」流程 ## 9. 后续步骤 * 还没接通飞书 → [如何连接智能体到飞书群组](/how-to/connect-feishu) * 想给字段加业务说明、提高 AI 准确度 → [表、字段备注](/concepts/data/annotations) * 想隐藏不希望 AI 看到的字段 → [字段隐藏](/concepts/data/hidden-fields) # 通过 MCP 使用 AskTable Source: https://docs.asktable.com/how-to/mcp AskTable 的 MCP server 把问数和管理能力按 Model Context Protocol 暴露给 AI agent。本页介绍接入方式和鉴权。 AskTable 提供官方 **MCP server**，把问数和管理能力按 [Model Context Protocol](https://modelcontextprotocol.io) 暴露成工具，让 Claude 等支持 MCP 的 AI agent 直接操作 AskTable。单一 server，共 43 个工具。 ## 接入方式 MCP server 通过 Streamable HTTP 提供服务，使用独立子域名： * 地址：`https://mcp.asktable.com/` * 鉴权：请求头 `Authorization: Bearer `（必传） 在 MCP 客户端里配置（以 Claude 系列的 `mcpServers` 为例）： ```json theme={null} { "mcpServers": { "asktable": { "type": "http", "url": "https://mcp.asktable.com/", "headers": { "Authorization": "Bearer <你的 API Key>" } } } } ``` 具体字段名以你的 MCP 客户端为准。 ## 后续步骤 * [命令行工具（CLI）](/how-to/cli) — 在终端里直接操作 AskTable * [在扣子（Coze）中使用](/how-to/connect-coze) — 把 AskTable 接进扣子机器人 # AskTable 文档 Source: https://docs.asktable.com/index AskTable 是面向非技术人员的 AI 数据分析工具，让数据分析像说话一样简单。 让数据分析像说话一样简单。 5 步完成从零到第一次对话 支持的数据库与连接配置