AskTable SDK
Project description
Python Client SDK(Python客户端SDK)
1 APIs(API 接口)
API 接口列表: https://api.asktable.com/
2 认证方法
需要在 Header 中增加 Authorization 字段,值为 Bearer <token>
,其中 <token>
为用户的 Token。
注意:新用户请联系 contact@datamini.ai
获得token。
3 安装
依赖 Python 3.9+。
pip install asktable
4 快速开始
-
命令行CLI
$ pip install asktable $ asktable -t <token> -- AskTable 客户端(0.7.19)初始化完成! -- 连接服务器(-a): https://api.asktable.com/ -- 使用Token (-t): token01 -- 您可以使用 'at' 来访问 AskTable,比如:通过 'at.datasources' 来查询数据源列表 完整的使用方法,请参考帮助文档:https://pypi.org/project/asktable/ In [1]: at.datasources.latest.ask('你好') Out[1]: [OK-2s]|| 你好!有什么可以帮助你的吗?
-
Python SDK
from asktable import AskTable at = AskTable(token='your_token') ds = at.datasources.create_from_local_file("your_excel_file_path") ds.ask('总共有多少行?')
5 完整示例
以下示例使用命令行CLI方式演示。
5.1 注册数据源
-
注册 MySQL 数据源
at.datasources.register( engine="mysql", access_config={ "host": "localhost", "port": 3306, "user": "root", "password": "", "db": "test" # 可选 "securetunnel_id": "atst_p94FEWbXDWWDW3VC" #可选 } ) Data Source ds_2MSqC5EUFawpK0nVOg8MXN: Wait for 1 seconds and check again. Current status: processing Data Source ds_2MSqC5EUFawpK0nVOg8MXN: Wait for 2 seconds and check again. Current status: processing Data Source ds_2MSqC5EUFawpK0nVOg8MXN: Wait for 3 seconds and check again. Current status: processing Data Source ds_2MSqC5EUFawpK0nVOg8MXN: Wait for 5 seconds and check again. Current status: processing Data Source ds_2MSqC5EUFawpK0nVOg8MXN: Wait for 8 seconds and check again. Current status: processing Data Source ds_2MSqC5EUFawpK0nVOg8MXN AI Process Success.
access_config
中的 securetunnel_id
为可选项,如果您的数据源需要通过 ATST 访问,请填写此字段。AskTable 会通过您的这个 ATST 来访问这个数据源,确保数据传输的安全性。
-
注册一个可下载的文件(Excel或CSV)
at.datasources.register( engine="csv", access_config={ "location_url": "https://example.com/path/to/myfile.csv", "location_type": "http", } )
-
上传并注册一个本地的文件(Excel或CSV)
In [69]: at.datasources.create_from_local_file(local_file_path="/DataMini/asktable/sample_data/tests/test_chart.xlsx", direct_to_oss=True) Out[69]: <ds_mrQq88Pu2DaBLCUZwgBAO: 月销售数据 >
5.2 查看和使用数据源
-
所有数据源
In [54]: at.datasources Out[54]: id created_at name type ds_1MEd5IA392sgt7mw5PcwgV 2024-01-21T17:09:18 高校讲师工作量汇总 excel ds_5DuPVZbOo5iRx9ZRWNtDCj 2024-01-22T15:44:52 求公式数据汇总 excel ds_2Vl6Y5bypIJE0J19ulmiBL 2024-01-28T19:03:02 2024天津公务员招考 excel ds_3IrvrL6oFd1SIQ6FEKUPCn 2024-02-03T11:34:45 学生成绩总览 excel ds_2TDFez0l0qiSwFLsGvRKvV 2024-02-25T14:40:14 杭州房产信息 csv
-
最新的数据源
In [55]: at.datasources.latest Out[55]: <ds_2TDFez0l0qiSwFLsGvRKvV: 杭州房产信息 >
-
根据ID精确查找
In [56]: at.datasources.get('ds_2TDFez0l0qiSwFLsGvRKvV') Out[56]: <ds_2TDFez0l0qiSwFLsGvRKvV: 杭州房产信息 >
-
根据Name查找(可能重名,返回List)
In [57]: at.datasources.get(name='杭州房产信息') Out[57]: [<ds_25vqFPq3wAgzcCVGoygBOO: 杭州房产信息 >, <ds_2eGWHUvUbWN0AAbke0aKIb: 杭州房产信息 >, <ds_2TDFez0l0qiSwFLsGvRKvV: 杭州房产信息 >]
-
删除数据源
In [65]: ds = at.datasources.latest.delete() # 删除最新的数据源 Out[65]: True
同时会删除这个数据源对应的 AskTable SecureTunnel Link(ATST Link)。
5.3 查看和管理数据源的Meta信息
-
查看Meta(在AskTable中管理的Meta)
In [15]: at.datasources.latest.meta Out[15]: test (测试环境数据库) ------------------------------ Table Name Table Desc Fields(analysed/all) alembic_version 数据库迁移版本控制表 1/1 chats 聊天记录表 4/4 users 用户信息表 2/2
-
查看 RuntimeMeta(运行时,即原文件或者原数据库中最新的Meta)
In [16]: at.datasources.latest.meta_runtime Out[16]: test ------------------------------ Table Name Table Desc Fields(analysed/all) alembic_version 0/1 chats 1/4 users 1/2
-
更新Meta(即将 RuntimeMeta 更新到 AskTable 中,并自动分析和识别含义)
In [17]: at.datasources.latest.meta.update() Data Source ds_39dJslzX5G2TDofefHJ0t9 Meta 状态为 processing,正在等待完成... 等待 1 秒后重新检查。当前状态: processing Data Source ds_39dJslzX5G2TDofefHJ0t9 Meta 更新成功。 Out[17]: test (测试环境数据库) ------------------------------ Table Name Table Desc Fields(analysed/all) alembic_version 数据库迁移版本控制表 1/1 chats 聊天记录表 4/4 users 用户信息表 2/2
-
查看 Meta 状态
In [21]: at.datasources.latest.meta.status Out[21]: 'success'
-
删除 Meta(将AskTable中保存的Meta删除)
In [18]: at.datasources.latest.meta.delete() Out[18]: True
-
查看示例问题
In [62]: ds = at.datasources.latest In [63]: ds.sample_questions Out[63]: '- 查询杭州房产的平均总价\n- 统计各区域房产数量 \n(为了方便沟通,您可以直接指定列名:城市, 区域, 子区域, 小区, 总价, 单价, 户型, 楼层, 建筑面积, 套内面积, 装修, 梯户比例, 电梯, 别墅类型, 挂牌日期, 产权, 房屋用途, 房龄, 链接)'
5.4 发起和管理对话
-
基于一个数据源,发起会话并提问
In [8]: answer = at.datasources.latest.ask('你好') Out[8]: [msg_5PvPIvwPofYG9HkUzjzzRc] [ai] [OK-10s] 你好!有什么可以帮助你的吗? [Just now]>
-
选择多个数据源,一起提问
In [9]: chat = at.chats.create(['ds_2MSqC5EUFawpK0nVOg8MXN', 'ds_34LANTyIJi0srCJrHFxRZ']) In [10]: answer = chat.ask('你好') In [11]: answer.to_dict() Out[11]: {'id': 'msg_4wQf4lD2AqDiPikRW4Tijk', 'chat_id': 'chat_G5g0FKbGQlljAKHrKz160', 'created': 1712287283, 'role': 'ai', 'content': {'status': 'OK', 'elapsed_time': 2, 'text': '你好!有什么可以帮到您的吗?', 'answer_file_url': None, 'answer_image_url': None, 'structure_queries': None, 'statistics': None}, 'reply_to_msg_id': 'msg_7aEuVCH8fX9BzlS3EvwKnl'}
-
查看所有对话
In [40]: at.chats Out[40]: id created datasource_ids human_msgs ai_msgs latest_msg chat_E90pdsNUlDE7wo8gsjahf 2024-01-06 12:10:00 ['ds_1ZAoAyIn1ph0lldief4cP5'] 2 2 2024-01-07 01:26:48 chat_ql7vWZEIqafqg9dMAaNpi 2024-01-07 05:35:03 ['ds_S0tdSsWcuB2HxEA1BQICE'] 0 0 chat_1SfzrRkiIlKyvHtOTbX7qW 2024-01-07 05:46:21 ['ds_6tWxUjnKbK2JwJRmLuPTj9'] 4 4 2024-01-07 05:50:59 chat_2WEHFozMZPFQhYkqLwvufZ 2024-01-07 10:34:15 ['ds_5Jydks0MbCJ3atBIHBC98'] 1 1 2024-01-07 10:35:02
-
获取最后一个对话
In [41]: at.chats.latest Out[41]: <Chat chat_6LYoQImReUun8gR8q32LZm [2024-02-06 06:33:47]>
-
根据ID查找对话
In [44]: at.chats.get('chat_1SfzrRkiIlKyvHtOTbX7qW') Out[44]: <Chat chat_1SfzrRkiIlKyvHtOTbX7qW [2024-01-07 05:46:21]>
-
查看某个对话的历史消息
In [43]: at.chats.latest.messages Out[43]: id created role content msg_1x0t6ch4KzZiSPFDbrL1iC 2 hours 59 minutes ago human 将B列的数据拆分为姓名、手机号和地址三列 msg_5D5bdJ2vBYjhpjlVuqyN5N 2 hours 59 minutes ago ai [OK-22s] 很抱歉,由于元数据中并未提供包含电话号码和地址的字段信息,我们无法直接从数据库中分割列B的数据为姓名、电话号码和地址三个独立的列。如果您能提供更详细的数据格式或者具体的分割规则,我们可能会有其他方式来帮助您处理这个问题。 msg_1rnZp94PzQeMetZxV2W3VC 2 hours 57 minutes ago human 看起来好像可以按照换行来拆分 msg_1igXXP1VBMSVx2iW8DENVt 2 hours 57 minutes ago ai [OK-34s] 已经根据您的要求将B列的数据拆分为姓名、手机号和地址三列。您可以查看处理好的数据。 [File:https://0vc.cc/KcZzK]
-
删除某个对话
In [45]: chat = at.chats.latest In [46]: chat.delete() Out[46]: True
5.5 AskTable Secure Tunnel (ATST) 安全隧道
AskTable Secure Tunnel (ATST) 是一种安全工具,允许 AskTable 服务通过安全隧道与内部本地数据库进行安全通信。此服务适用于需要确保数据传输安全性的企业环境。
-
启动一个新的 AskTable Secure Tunnel 之前,需要获得一个唯一的
securetunnel_id
。from asktable import AskTable at = AskTable(token='your_token') # 创建新的安全隧道Key atst = at.securetunnels.create() print(f"SecureTunnel Created: {atst.key}")
-
查看所有 ATST 列出所有已创建的 ATST 信息。
In [2]: at.securetunnels Out[2]: key created_at atst_p94PzQeMetZxV2W3VC 2024-01-06 12:10:00 atst_p94PzQeMetZxV2W3VC 2024-01-07 05:35:03 atst_p94PzQeMetZxV2W3VC 2024-01-07 05:46:21 atst_p94PzQeMetZxV2W3VC 2024-01-07 10:34:15
-
获取 ATST 的配置信息
In [2]: at.securetunnels.get('atst_p94PzQeMetZxV2W3VC') Out[2]: { "id": "atst_p94PzQeMetZxV2W3VC", "atst_server_host": "atst-server.asktable.com", "atst_server_port": 7077, "links": [ { "id": "link_1", "target_host": "10.1.2.3", "target_port": 3306, "proxy_port": 6001, }, { "id": "link_1", "target_host": "10.1.2.4", "target_port": 3306, "proxy_port": 6002, }, ]}
-
获取某个ATST上绑定的所有Link
In [3]: at.securetunnels.get('atst_p94PzQeMetZxV2W3VC').links
Out[3]:
5.6 设置角色和权限
AskTable 的访问控制是通过访问策略定义和角色定义来实现的。
-
创建访问策略 访问策略(Access Policy)定义的是某个人能访问(或不能访问)的数据集。
from asktable import AskTable at = AskTable(token='your_token') # 允许访问用户表,但只能访问某个城市的数据 policy = at.policies.create( permission="allow", name="user_policy_shanghai", datasource_ids="ds_2MSqC5EUFawpK0nVOg8MXN,ds_34LANTyIJi0srCJrHFxRZ", tables_regex_pattern="^(user)_.*$", fields_regex_pattern=".*", rows_filters=[ "ds_1.*.user.city_id = {city_id}" ] ) print(f"Policy Created: {policy.name}")
-
创建角色。这使得可以根据角色控制其数据访问权限。
# 创建角色示例 role = at.roles.create( name="city_manager", description="Manager role for a city", ) print(f"Role Created: {role.name}") # 为角色绑定策略 role.attach_policies(policy_names=[policy.name]) print(f"Policies Attached: {policy.name}")
-
通过扮演角色来发起对话。这个角色决定了用户在该会话中可以访问哪些数据。
# 使用角色访问数据示例 chat = at.chats.create( ['ds_2MSqC5EUFawpK0nVOg8MXN', 'ds_34LANTyIJi0srCJrHFxRZ'], { "role_name": "city_manager", "role_variables": { "user_id": "123", "city_id": "310" } } ) response = chat.ask('Show me the user data for Shanghai.') print(response)
-
查看所有的策略
In [1]: at.policies Out[1]: id name datasource_ids schemas_regex_pattern tables_regex_pattern fields_regex_pattern rows_filters modified_at policy_7ANpC68WihJm0zkyRll5Do policy1 ds_UJDPngVNVLn7aKwvvWGTx 2024-05-05T10:49:29 policy_7ANpC68WihJm0zkyRll5Do policy2 ds_UJDPngVNVLn7aKwvvWGTx 2024-05-05T10:49:29
-
查看和管理某个策略
# 根据ID policy1 = at.policies.get('policy_7ANpC68WihJm0zkyRll5Do') # 根据Name policy2 = at.policies.get(name='policy1') # 获取最新的策略 policy3 = at.policies.latest # 修改 policy1.update(name='policy2', fields_regex_pattern='.*') # 删除 policy1.delete()
-
查看所有的角色
In [8]: at.roles Out[8]: id name modified_at role_41OHLVTiDZNDBukDhrMiJk role1 2024-05-05T10:53:34
-
获取和管理某个角色
# 根据ID role = at.roles.get('role_41OHLVTiDZNDBukDhrMiJk') # 根据Name role = at.roles.get(name='role1') # 获取最新的角色 role = at.roles.latest # 修改角色 role.update(name='role2') # 删除角色 role.delete()
-
获取和管理某个角色的策略
# 全部 policies = role.policies # 根据策略ID policy = role.policies.get('policy_6m2DGTvM6tC64cyF2cYjAJ') # 删除策略 policy.delete()
6. 错误处理
6.0 OK 正确返回
In [25]: at.chats.get('chat_5lSeeLn7KMScVCYjVNewFS').messages
Out[25]:
id created role content reply_to_msg_id
msg_43ZYqK5kMjr3xMIPqxgVxq 5 minutes ago human 最晚入职是谁
msg_4Bf8mRqPYk5U9bS99qFsT4 4 minutes ago ai [OK-7s] 最晚入职的员工是陈敏,员工编号为5,身份证号为100200200001012222,联系电话为13800000001。 msg_43ZYqK5kMjr3xMIPqxgVxq
In [26]: at.chats.get('chat_5lSeeLn7KMScVCYjVNewFS').messages.get('msg_4Bf8mRqPYk5U9bS99qFsT4')
Out[26]: [msg_4Bf8mRqPYk5U9bS99qFsT4] [ai] [OK-7s] 最晚入职的员工是陈敏,员工编号为5,身份证号为100200200001012222,联系电话为13800000001。 [4 minutes ago]>
In [27]: msg = at.chats.get('chat_5lSeeLn7KMScVCYjVNewFS').messages.get('msg_4Bf8mRqPYk5U9bS99qFsT4')
In [28]: msg.answer.to_dict()
Out[28]:
{'status': 'OK',
'elapsed_time': 7,
'text': '最晚入职的员工是陈敏,员工编号为5,身份证号为100200200001012222,联系电话为13800000001。',
'files': None,
'charts': None,
'query_insights': [{'question': '查询数据库中最晚入职的员工信息。\r\n\r',
'datasource': 'ds_1pv7a93n2LQr5DHHX64ECI',
'results': [{'query': 'SELECT * FROM test.employees ORDER BY employee_id DESC LIMIT 1',
'result_info': {'row_count': 1,
'column_count': 4,
'columns': ['employee_id', 'name', 'id_number', 'phone_number']},
'query_time_ms': 38}],
'query_time': 3}],
'payload': {'recognized_addresses': None, 'error_type': '', 'error_msg': ''}}
6.1 QAErrorCannotHandle 无法处理
In [18]: at.chats.latest.messages
Out[18]:
id created role content reply_to_msg_id
msg_40rEzS9Pi6cKA910qZe9PN Just now human 年龄最大的员工是谁
msg_3zbA7gvdJFiUG0x5xM7fAj Just now ai [ERROR-6s] 没有找到相关信息 msg_40rEzS9Pi6cKA910qZe9PN
In [19]: msg = at.chats.latest.messages.get('msg_3zbA7gvdJFiUG0x5xM7fAj')
In [20]: msg
Out[20]: [msg_3zbA7gvdJFiUG0x5xM7fAj] [ai] [ERROR-6s] 没有找到相关信息 [Just now]>
In [21]: msg.answer.to_dict()
Out[21]:
{'status': 'ERROR',
'elapsed_time': 6,
'text': '没有找到相关信息',
'files': None,
'charts': None,
'query_insights': None,
'payload': {'recognized_addresses': None,
'error_type': 'QAErrorCannotHandle',
'error_msg': "The 'age' field is not present in the employees table metadata provided."}}
以上步骤展示了如何在 AskTable 中通过角色和权限管理功能来精细控制数据访问权限,从而确保数据隐私和安全。
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for asktable-0.17.8-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3139cc8b8874e71cc59e66ef22a93399844e42d346e1194633b7d33274204bc4 |
|
MD5 | 5f0e3b07050b21ae4e1e925360bfcb1b |
|
BLAKE2b-256 | df75ea3bb57f1068edfb0a8dccc68b2f29f21f65e7eb48342f79b7eceb984fe7 |