析言GBI使用指南
析言GBI提供丰富的版本规格选项，您可按需选择。针对产品使用中的常见问题，本文档提供了问题解答及操作指导，您可根据所选版本进行问题自查及效果优化。
简介
析言GBI是基于阿里云通义大语言模型在数据分析领域专门增强的原生数据助理，通过自然语言交互实现NL2SQL、数据问答、分析、洞察等多维度的大模型智能分析应用，适用于业务变化较快、数据分析时效性强的一线业务场景。
操作指引
析言GBI产品入口：登录阿里云百炼析言GBI，。点击“立即体验”即可进入析言控制台页面。析言GBI为每个客户提供200个问题的免费试用额度。超出免费额度后，如需继续使用，请按需购买产品规格。
当试用或购买某个产品规格后，您需要先完成初始化。您可以按照如下步骤进行初始化配置，将您的数据库连接到析言GBI。
关联并授权析言访问指定数据库；
配置您授权析言访问的数据表schema信息；
配置您在使用析言进行问答时可能涉及的业务知识。
数据库连接
官方预置数据库
析言GBI支持自定义数据库和官方预置数据库。如果您希望测试析言GBI的功能但暂时没有合适的自定义数据库，可以选择使用官方预置数据库。
查看官方预置数据库
官方预置的数据库包括三张数据表：消费者信息表（customers）、订单信息表（orders）以及商品信息表（products）。您可以查看各数据表字段及其表内容。
在左侧导航栏点击数据表管理，再单击官方数据库中的查看详情查看官方预置数据库中的数据表。
在数据表的操作列单击查看详情，查看数据表字段信息。
单击预览数据表查看表内容。
使用官方预置数据库
您可以在官方数据库中预览数据表内容，并根据数据表内容进行提问来体验析言GBI的产品能力及其他使用方式。
在析言GBI首页的数据库页签中，单击使用官方预置数据库。
在下方输入框中单击鼠标左键，会显示预置的推荐问题，您可选择任意一个问题开启对话，测试析言GBI的功能。
配置数据库
首次登录控制台时，您需要在数据管理中进行数据信息维护。在左侧导航栏点击数据表管理，进行数据库授权。
析言支持关联公网可访问的MySQL或PostgreSQL协议数据库以及VPC访问数据库，包括AnalyticDB PostgreSQL版、Hologres、MySQL和PostgreSQL。
重要每个业务空间下仅能关联一种类型的数据库，如需更改，可取消授权并重新连接新的数据库。
在公网访问数据库中连接MySQL或PostgreSQL数据库时，请确保您填写的数据库实例IP/域名为公网可访问的地址，这里的数据库IP/域名可以是您在阿里云购买的云上数据库地址，或本地机房的数据库服务地址。如果遇到连接失败的情况，请检查数据库访问是否有IP白名单限制。如有限制，请在白名单中添加析言GBI的IP地址：39.107.142.91。
在VPC访问数据库中连接AnalyticDB PostgreSQL前，需要先“授权ADB实例”。若未进行ADB实例授权，则在授权ADB实例弹窗中，点击授权联接按钮会先进行ADB实例授权。执行此操作会自动创建一个服务关联角色。该权限将允许阿里云百炼析言GBI访问您的云原生数据仓库 AnalyticDB PostgreSQL版资源，使用该权限可查询数据库、表、列等信息，执行SQL查询数据相关功能。
授权ADB实例后，需要填写表单，授权析言GBI连接您的ADB数据库。
Region：必填，可选范围有北京、上海、杭州、深圳等，默认北京。
数据库实例：必填，Region范围内的数据库实例，仅支持选择一个实例.
用户名和密码：必填，访问已选ADB数据库实例的用户名和密码。
在VPC访问数据库中连接Hologres、MySQL和PostgreSQL 数据库前，用户VPC与析言VPC需进行网络层面打通。打通网络的具体操作，请参见反向网络访问VPC打通。网络打通后，请填写关联数据库信息进行数据库关联。
连接数据库成功后，选择授权析言GBI访问的数据表信息，以完成数据表同步。当数据库中存在大量数据表时，此数据同步过程可能需要更多时间。数据表同步成功后，您可在页面列表中进行管理。
配置数据表schema信息
数据表同步成功后，为使析言GBI能正常接入，需要您在数据表管理维护该表的schema信息，同时确保和源数据库的结构一致。
基础信息：包含数据表描述、数据表的主键、外键信息。
数据表描述：当前表记录的数据内容与颗粒度等，例如：变电站安装记录表，用于xxxx；
数据表主键：用于保证数据完整性，即确保在该表格中每一行记录都是独一无二的，用来快速查找和引用特定记录；
数据表外键：在不同表之间建立联系，用于跟其他表格进行关联；例如： 表a.列名=表b.列名1；表之间若有外键，必须配置，否则表格之间join可能有误。
列信息：
列描述：用简单凝练的语言描述该列的具体含义；
列中文名：选填，在列描述信息缺失的情况下，根据列中文名理解数据表信息；
枚举值：对于枚举类型的列至关重要，需要罗列该列中存储的全部值，在有值含义映射的情况下，需为值设置其对应的映射值。可通过从数据库中同步枚举值来便捷操作，析言将从数据库中拉取去重后的至多99个枚举值。有一些关键的要求和最佳实践需要注意，以确保其有效性和可靠性：
值的唯一性：每个枚举值应该在预定义的范围内是唯一的，不能有重复的值。
值的描述性：枚举值应尽可能具有描述性，这样能够直观地表示其含义。例如，用
'active'和'inactive'比1和0更具可读性。合理的值数量：枚举值的数量不宜过多，过多可能会增加代码复杂度和维护成本。一般建议控制在10个以内。
数据文件（仅支持在标准版mix中使用）
在析言GBI中，支持上传.xlsx格式的Excel数据文件。上传数据文件后，您可以针对该文件进行提问，析言GBI将根据问题对已上传的数据文件中的表格内容进行分析，并生成答案、绘制可视化图表。
在析言GBI首页的左下角选择标准版mix。
在页面右侧区域，选择数据文件页签。
点击上传文件，按照数据文件上传弹窗中的要求，修改Excel文件并上传。
数据文件上传成功后，页面会展示已上传并解析成功的数据表信息。您可以在下方输入框中输入问题开启对话。
在当前页面您还可以执行以下操作：
编辑表信息：编辑数据表的描述信息以及表中每个字段的描述信息，以便准确识别数据表和字段的用途。
删除文件：单击删除文件，可删除数据表。
企业数据管理
为了帮助析言GBI更好地理解您在数据分析中的目标表述，企业数据管理模块提供了三种工具，可以满足您的业务场景需要。
知识名词解释
对于业务场景的专有名词，可以在知识名词解释中进行配置。例如：在使用自然语言提问时，通常会出现“咨询转化率”一词，但关联数据表中并没有“咨询转化率”列，其值是经“有咨询且下单成功客户”列汇总后，与“有咨询客户”列汇总的结果相除获得。对于这种情况，您可以在该词条描述下定义该指标的计算口径。
同义词解释
使用自然语言提问时，经常涉及某个词汇的多种说法，这些说法被称为同义词。在同义词解释中，您可以维护同义词列表。例如：数据表实际存储值为“北京市”，在使用自然语言提问时，可以使用同义词“首都”来替代。
为提升同义词识别准确度，建议在配置同义词时，将同义词关联到数据表具体的某一列上。
业务逻辑解释
当您使用自然语言提问时，企业特有的业务逻辑通常需要配置在业务逻辑解释中。例如，当查询包含“本月”时，您可以将业务逻辑解释配置为“指从本月1日至今天的数据汇总”。
业务逻辑解释可作为对模型输出进行业务校正的高级指导功能，针对模型对数据表schema信息理解不准确、SQL生成不准确的情况下，通常可以通过优化业务逻辑解释来进行效果调优。
业务逻辑分为全局和智能两种。全局型业务逻辑对所有用户的问题生效。智能业务逻辑由模型根据用户问题内容选择性生效。
模型优化案例管理
在尝试调整问题问法及数据管理后，模型依然无法输出预期结果的情况下，您可以通过添加优化案例来指导模型进行学习。在标准版mix中，析言开放案例自运营管理能力，可供用户在不对模型本身进行定制的情况下，依然可以通过案例管理来指导模型进行一类问题的自学习。
使用说明：优化案例管理提供通配符管理与案例库管理两项能力，其中通配符需与案例库联合使用，请先添加通配符，而后添加案例库。添加完毕后，系统需要进行数据解析供模型自学习，请稍等几分钟后再使用。
通配符管理
通配符是一种可以被一个或多个字符进行模糊替代的高级词汇，例如某通配符A为【品牌】，其枚举值为“小米”、“华为”、"vivo"、“oppo”；某通配符B为【职级】，其枚举值为“初级工程师”、“中级工程师”、“高级工程师”。在实际的问题问法中可能包含某个通配符的某个枚举值，此类问法在后续进行案例管理时，无需为每个枚举值逐一添加案例，模型将根据通配符的设置内容进行智能理解。
案例库管理
添加案例可以有效提升模型解决一类问题的准确率。一条案例包含一个问题的问法描述与其预期正确执行的完整SQL内容。在设置案例时，若该案例的问法描述中包含某通配符的某个枚举值信息，请确保已在通配符管理中完成设置。
模型输出干预
如果多次调整问题问法和数据管理后，模型依然回答错误，您可以设置特定回复来干预模型输出。
干预的问法描述及预期正确执行的完整SQL不具备泛化特性。
为避免设置过多干预条件产生不可预知的负向影响，请谨慎设置干预条件，并尽可能减少该功能的使用频率。
首页问答
您可以在析言GBI首页的数据库页签中，选择自定义数据库或使用官方预置数据库，再在输入框内输入您需要查询的问题，点击
提交问题。
问题提交后，析言GBI将按照五个步骤解析您的问题并生成相应答案。
针对生成的答案您可以执行以下操作。
操作
说明
重新生成答案
点击重新生成时，原答案会保留，您可以在卡片底部进行切换查看，默认停留在最近一次生成结果页。
目前，析言GBI最多支持重新生成5次答案。
图表切换
在图表的上方可点击
切换图表类型（柱状图、折线图、饼图）。切换图表仅改变图表的展示形式，不会重新生成结果。
结果导出
点击下载结果，把本次问题及析言GBI生成结果下载至本地。
下载文件格式：.csv
下载文件名称：Request ID.csv
问题自查
支持的数据库类型
问题类型 | 优化指导 |
目前析言支持哪些类型的数据库？ | 析言支持联接公网可访问的MySQL或PostgreSQL协议数据库，对于上述两种协议的数据库类型不做限制，可根据数据库的协议选择对应的类型进行添加。 |
何时支持内网数据库？ | 2024.7月中旬析言开放关联阿里云云上内网数据库，ADB-PG、Hologres、PolarDB。其中ADB-PG通过DataAPI方式对接，需要用户在使用析言时进行访问授权；Hologres、PolarDB通过反向网络访问对接，需要用户提前进行网络联通配置。 敬请期待。 |
数据库连接问题自查
错误类型 | 常见错误操作 | 正确指导 |
连通性错误 | URL格式错误 | MySQL连接格式为：jdbc:mysql://host:port/db_name； PostgreSQL连接格式为：jdbc:postgresql://host:port/db_name。 其中，host是数据库的域名，port是端口号，db_name是授权的数据库名。 |
数据库连通错误，URL非公网可访问地址 | 填写的URL需要是公网可访问的地址。host部分不能填写localhost。如果数据库是在阿里云购买的，您可以在数据库实例的数据库连接菜单下找到公网host。 | |
数据库连通错误，数据库有访问IP限制 | 此情况下，您需要将析言GBI公网IP：39.107.142.91添加到白名单。 如果数据库是在阿里云购买的，您可以在数据库的安全性菜单里配置访问IP白名单。 如果数据库是部署在ECS上的实例，您需要在ECS的安全组里添加入方向IP白名单。 | |
账号密码错误 | 账号错误 | 应填写访问数据库用户名，非数据库名称。 |
效果不达预期问题自查
问题类型 | 优化指导 |
一个用户问题中包含多个查询问题 | 当前，一个用户问题只能生成一条查询SQL。如果用户问题包含多个查询，仅输出一个问题的查询SQL。建议您将复杂问题拆分为多个简单问题。 |
补充数据表描述和列schema信息后生成SQL依然不符合预期 | 您可以尝试添加问题中所包含的业务逻辑。 |
日期相关查询自查
问题类型 | 优化指导 |
日期查询错误 | 数据库中的日期列，建议使用YYYY-MM-DD格式，并且在“列描述中填写：日期列，格式为YYYY-MM-DD”，尽量不要使用YYYYMMDD或者MMDDYYYY等格式。 |
当前日期相关的错误 | 建议在问题中指出明确日期，比如2024-05-30的销量；不要默认省去一些信息，比如“4月20日”这个问法中默认省去了“今年”导致模型难以推理。 |
其他错误自查
问题类型 | 优化指导 |
列不存在 | 很多时候列不存在的错误是模型没有理解列的名字，可以考虑在列描述增加列的中文含义； 列名尽量不要使用中文名，推荐使用英文名； |
表不存在 | "表不存在"错误常发生于模型不理解哪个表能解决用户的问题。建议您配置表描述，用中文说明这个表的用途和存储内容。 |
表join失败 | 这种错误常见于表的外键缺失，可以配置外键以提高这个链接的效果 |
group by错误，错误提示形如 Expression *** of select list is not in group by clause ..... | 需要在MySQL配置中关闭ONLY_FULL_GROUP_BY。 请在 |
选表错误 | 目前模型对于表数量过多的情况下，在选表精准度上有一定困难，推荐关联表数量不超过20张，并且在容易混淆的相似表中明确定义表描述信息。 |
常见问题及解答
析言GBI的正式版和试用版本有什么区别？
答：试用版功能与正式版相同。试用版目前有开放少量免费额度。
每个业务空间下仅能关联一种类型的数据库，是只能关联一个数据库？还是在MySQL/PostgreSQL下可以链接多个数据库？
答：一个业务空间下只能连接一个数据库，目前不支持跨库查询，如果实际业务中需要多数据库查询，可以通过业务空间进行隔离，不同的业务空间使用不同的数据库。
如果只能链接一个数据库情况下，对于实际业务中需要对多数据库查询，有什么好的建议？
答：目前不支持跨库查询，建议根据业务场景进行业务空间隔离，不同业务空间使用不同的数据库。
析言支持私有化吗？
答：析言支持数据库在本地，服务在公共云的混合部署。目前不支持私有化部署。
析言产品的并发是指的什么？ 同时有2个用户访问，第二个用户需要排队吗？
答：并发指的是系统同时处理的请求数，如果只购买1个并发，那么系统在同一时刻只能处理一个请求，在当前请求处理完之前，第二个请求会被拒绝。
自然语言对应生成SQL是通过列描述还是列中文名？
答：优先列描述。
多个业务空间可以复用同一个GBI吗？
答：不同业务空间数据是隔离的，无法复用。
析言支持定义默认查询条件吗？
答：目前还不支持。
联系我们
如您在使用析言GBI的过程中有任何问题，欢迎加入钉钉群咨询、交流和反馈。
加入钉钉群的方式：您可以使用钉钉扫描如下二维码，或搜索钉钉群号：94725009401。
