详细介绍：PandasAI：ChatBI的极简上手版学习（一）

所有教程都是v3版本

---

文章目录

• 1 什么是 PandasAI？
• • 1.1 安装
  • 1.2 快速开始： 设置您的首次对话
• 2 PandasAI重要模块
• • 2.1 加载模型
  • • 2.1.1 openai的加载
    • 2.1.2 其他大语言模型
    • 2.1.3 大模型参数设置
  • 2.2 数据集加载
  • • 2.2.1 dataframe构造来源：CSV + excel
    • 2.2.1 dataframe构造来源：Snowflake扩展（企业版）
    • 2.2.2 dataframe构造来源：sql
    • 2.2.3 SmartDataframe（旧版）
  • 2.3 语义信息create
  • • 2.3.1 dataframe提供语义信息
    • 2.3.2 数据源定义语义信息：SQL 数据库
  • 2.4 输出格式规范
  • • 2.4.4 Generated Code中间代码检查
    • 2.4.5 图表输出
  • 2.5 使用视图
  • • 2.5.1 python配置
    • 2.5.2 yaml文件定义
  • 2.6 AI Dashboards仪表盘
  • 2.7 Memory内存存储模块
  • • 2.7.1 Memory内存基础模块
    • 2.7.2 agent中的Memory
    • 2.7.3 加载memory成为get_system_prompt
• 3 训练你的agent
• • 3.1 Instructions training 指令训练 (类似RAG)
  • 3.2 Q/A training - 问答对存储
  • 3.3 本地向量存储训练模型
  • 3.4 使用沙箱环境
• 4 Chat 大致使用方法
• • 4.1 chat方法工作流程
  • 4.2 提出具体问题
  • 4.3 适当使用输出类型
  • 4.4 明智处理大型数据集
• 5 Agent
• • 5.1 使用agent整合数据+查看历史消息

---

1 什么是 PandasAI？

v3版本的教程文档：https://docs.pandas-ai.com/v3/introduction
github地址：https://github.com/sinaptik-ai/pandas-ai
官方正式网址：https://pandas-ai.com/

PandasAI 通过添加自然语言功能扩展了 pandas DataFrame 的强大能力。您无需编写复杂的 pandas 代码，只需用简单的英语提问即可获得智能响应。这就像拥有一个理解您数据的分析师助手，能为您提供洞察、生成可视化图表，并代表您执行复杂的分析。

1.1 安装

首先，让我们在您的系统上安装 PandasAI。PandasAI 需要 Python 3.8 或更高版本（但低于 3.12）。

pip install "pandasai>=3.0.0b2"

或者如果您更喜欢使用 Poetry：

poetry add "pandasai>=3.0.0b2"

每个 LLM 扩展都会自动将 PandasAI 核心包作为依赖项安装，因此您无需单独安装

# 用于 LiteLLM（多 LLM 提供商）
pip install pandasai-litellm

1.2 快速开始： 设置您的首次对话

PandasAI 的核心功能是与数据进行对话。让我们从一个简单的示例开始，了解其工作原理：

import pandasai as pai
from pandasai_openai.openai import OpenAI
llm = OpenAI("YOUR_OPENAI_API_KEY")
# 使用您的 LLM 配置 PandasAI
pai.config.set({
"llm": llm
})
# 创建示例 DataFrame
df = pai.DataFrame({
"country": ["United States", "United Kingdom", "France", "Germany", "Italy", "Spain", "Canada", "Australia", "Japan", "China"],
"revenue": [5000, 3200, 2900, 4100, 2300, 2100, 2500, 2600, 4500, 7000]
})
# 向您的数据提问
response = df.chat('Which are the top 5 countries by sales?')
print(response)
>>> 中国、美国、日本、德国、澳大利亚

就是这样！您刚刚完成了与数据的首次对话。PandasAI 理解了您的自然语言问题，分析了数据，并提供了清晰的答案。

多表格的使用：

import pandasai as pai
from pandasai_openai.openai import OpenAI
employees_data = {'EmployeeID': [1, 2, 3, 4, 5],'Name': ['John', 'Emma', 'Liam', 'Olivia', 'William'],'Department': ['HR', 'Sales', 'IT', 'Marketing', 'Finance']
}
salaries_data = {'EmployeeID': [1, 2, 3, 4, 5],'Salary': [5000, 6000, 4500, 7000, 5500]
}
llm = OpenAI("OPEN_AI_API_KEY")
pai.config.set({"llm": llm
})
employees_df = pai.DataFrame(employees_data)
salaries_df = pai.DataFrame(salaries_data)
pai.chat("Who gets paid the most?", employees_df, salaries_df)
>>> Olivia gets paid the most.

2 PandasAI重要模块

2.1 加载模型

文档地址：https://docs.pandas-ai.com/v3/large-language-models

需要安装

pip install pandasai-litellm

2.1.1 openai的加载

安装：

# Using pip
pip install pandasai-openai

然后

import pandasai as pai
from pandasai_openai import OpenAI
llm = OpenAI(api_token="my-openai-api-key")
# Set your OpenAI API key
pai.config.set({"llm": llm})

包括Azure OpenAI models

import pandasai as pai
from pandasai_openai import AzureOpenAI
llm = AzureOpenAI(api_base="https://.openai.azure.com/",api_key="my-azure-openai-api-key",deployment_name="text-davinci-003")  # The name of your deployed model
pai.config.set({"llm": llm})

2.1.2 其他大语言模型

可参考文档：
https://docs.litellm.ai/docs/providers
基本主流的大模型都是有的(没有kimi)

• OpenAI (gpt-4.1-mini, gpt-4等)
• Anthropic (claude-2, claude-instant-1等)
• Google (gemini-pro, palm2等)
• Azure OpenAI
• AWS (Bedrock, SageMaker)
• Mistral AI
• Cohere
• Hugging Face
  

笔者尝试的时候是使用modelspace的qwen千问模型：

import pandasai as pai
from pandasai_litellm.litellm import LiteLLM
# Initialize LiteLLM with your OpenAI model
base_url = 'https://dashscope.aliyuncs.com/compatible-mode/v1'
llm = LiteLLM(base_url = base_url,model="dashscope/qwen-turbo", api_key=apikey)

这里记住要去获取base_url 以及 apikey，在千问平台里可以拿到以及挑选模型
千问可以使用的模型名单：

2.1.3 大模型参数设置

temperature=0的作用
语言模型中的temperature参数控制输出的随机性。较高的temperature会增加响应的多样性和创造力，而较低的temperature则使模型更具可预测性和保守性。将temperature设置为0本质上关闭了随机性，使模型在每一步选择最可能的下一个词。

temperature=0的影响

• 可预测的响应：模型将始终选择最可能的路径，从而导致输出的高度可预测性。
• 创造力：可预测性的权衡是响应的创造力和变化减少，因为模型不会探索不太可能的选项。

用seed增强控制
seed参数是另一个增强确定性的工具。它设置了用于模型的随机数生成器的初始状态，确保每次运行时使用相同的“随机”数序列。该参数与temperature=0结合使用时，提供了更高的可预测性。

import pandasai as pai
# 示例DataFrame
df = pai.DataFrame({
"country": ["United States", "United Kingdom", "France", "Germany", "Italy", "Spain", "Canada", "Australia", "Japan", "China"],
"gdp": [19294482071552, 2891615567872, 2411255037952, 3435817336832, 1745433788416, 1181205135360, 1607402389504, 1490967855104, 4380756541440, 14631844184064],
"happiness_index": [6.94, 7.16, 6.66, 7.07, 6.38, 6.4, 7.23, 7.22, 5.87, 5.12]
})
# 配置LLM
pai.config.set("temperature", 0)
pai.config.set("seed", 26)
df.chat('Which are the 5 happiest countries?') # 答案应该在设备之间（大致）一致。

2.2 数据集加载

参考文档：https://docs.pandas-ai.com/v3/data-ingestion

加载数据的几种方式：

• CSV和Excel文件：使用简单的Python函数直接从文件加载数据
• SQL数据库：使用我们的扩展连接到各种SQL数据库
• 云数据：使用我们的专用扩展处理企业级数据（需要企业许可证）

扩展	使用poetry安装	使用pip安装	需要企业许可证？
pandasai_sql	poetry add pandasai-sql[postgres]	pip install pandasai-sql[postgres]	否
pandasai_yfinance	poetry add pandasai-yfinance	pip install pandasai-yfinance	否
pandasai_snowflake	poetry add pandasai-snowflake	pip install pandasai-snowflake	是
pandasai_databricks	poetry add pandasai-databricks	pip install pandasai-databricks	是
pandasai_bigquery	poetry add pandasai-bigquery	pip install pandasai-bigquery	是
pandasai_oracle	poetry add pandasai-oracle	pip install pandasai-oracle	是

2.2.1 dataframe构造来源：CSV + excel

使用PandasAI从CSV文件加载数据非常简单：

import pandasai as pai
# 基本的CSV加载
file = pai.read_csv("data.csv")
# 在CSV上使用语义层
df = pai.create(
path="company/sales-data",
df=file,
description="来自我们零售店的销售数据",
columns={
"transaction_id": {"type": "string", "description": "每笔销售的唯一标识符"},
"sale_date": {"type": "datetime", "description": "销售的日期和时间"},
"product_id": {"type": "string", "description": "产品标识符"},
"quantity": {"type": "integer", "description": "销售的单位数量"},
"price": {"type": "float", "description": "每单位的价格"}
},
)
# 与数据框聊天
response = df.chat("哪个产品的销售最高？")

再来看一下如何读取excel：

# 文件读入
filepath = "tests/examples/data/sample_single_sheet_data.xlsx"
result = pandasai.read_excel(filepath, sheet_name=sheet_name)
# BytesIO open的方式读入
with open("tests/examples/data/sample_single_sheet_data.xlsx", "rb") as f:file_content = BytesIO(f.read())
result = pandasai.read_excel(file_content)

2.2.1 dataframe构造来源：Snowflake扩展（企业版）

首先，安装扩展：
```bash
poetry add pandasai-snowflake
# 或
pip install pandasai-snowflake

然后使用它：

name: sales_data
source:
type: snowflake
connection:
account: your-account
warehouse: your-warehouse
database: your-database
schema: your-schema
user: ${SNOWFLAKE_USER}
password: ${SNOWFLAKE_PASSWORD}
table: sales_data
destination:
type: local
format: parquet
path: company/snowflake-sales
columns:
- name: transaction_id
type: string
description: Unique identifier for each sale
- name: sale_date
type: datetime
description: Date and time of the sale
- name: product_id
type: string
description: Product identifier
- name: quantity
type: integer
description: Number of units sold
- name: price
type: float
description: Price per unit
transformations:
- type: convert_timezone
params:
column: sale_date
from: UTC
to: America/Chicago
- type: calculate
params:
column: revenue
formula: quantity * price
- type: round
params:
column: revenue
decimals: 2
update_frequency: daily
order_by:
- sale_date DESC
limit: 100000

2.2.2 dataframe构造来源：sql

PandasAI提供了一个SQL扩展，让您可以使用SQL、PostgreSQL、MySQL和CockroachDB数据库。为了使库轻量且易于使用，库的基本安装不包括此扩展。您可以使用pip轻松安装所需数据库的扩展：

pip install pandasai-sql[postgres]
pip install pandasai-sql[mysql]
pip install pandasai-sql[cockroachdb]

安装扩展后，您可以使用语义数据层并执行数据转换。

sql_table = pai.create(
path="example/mysql-dataset",
description="来自MySQL数据库的心脏病数据集",
source={
"type": "mysql",
"connection": {
"host": "database.example.com",
"port": 3306,
"user": "${DB_USER}",
"password": "${DB_PASSWORD}",
"database": "medical_data"
},
"table": "heart_data",
"columns": [
{"name": "Age", "type": "integer", "description": "患者的年龄（以年为单位）"},
{"name": "Sex", "type": "string", "description": "患者的性别（M = 男性，F = 女性）"},
{"name": "ChestPainType", "type": "string", "description": "胸痛类型（ATA, NAP, ASY, TA）"},
{"name": "RestingBP", "type": "integer", "description": "静息血压（单位：mm Hg）"},
{"name": "Cholesterol", "type": "integer", "description": "血清胆固醇（单位：mg/dl）"},
{"name": "FastingBS", "type": "integer", "description": "空腹血糖 > 120 mg/dl（1 = 是，0 = 否）"},
{"name": "RestingECG", "type": "string", "description": "静息心电图结果（正常，ST，LVH）"},
{"name": "MaxHR", "type": "integer", "description": "达到的最大心率"},
{"name": "ExerciseAngina", "type": "string", "description": "运动诱发的心绞痛（Y = 是，N = 否）"},
{"name": "Oldpeak", "type": "float", "description": "相对于静息的运动诱发的ST压低"},
{"name": "ST_Slope", "type": "string", "description": "峰值运动ST段的斜率（上升，平坦，下降）"},
{"name": "HeartDisease", "type": "integer", "description": "心脏病诊断（1 = 存在，0 = 不存在)"}
]
}
)

2.2.3 SmartDataframe（旧版）

文档：https://docs.pandas-ai.com/v3/smart-dataframes

此文档页面用于向后兼容性。对于新项目，我们建议使用新的语义数据框。

要从 SmartDataframe 迁移到新的语义数据框：

• 替换 SmartDataframe 导入为语义数据框导入
• 更新配置以使用 pai.config.set()
• 使用新的 .chat() 方法语法

示例迁移：

# 旧代码
from pandasai import SmartDataframe
smart_df = SmartDataframe(df)
# 新代码
import pandasai as pai
df = pai.DataFrame(df)

SmartDataframe 类是之前在 PandasAI 中创建数据框的方式。它提供了与当前语义数据框类似的功能，但 API 不同。

from pandasai import SmartDataframe
import pandas as pd
# 创建一个 pandas DataFrame
df = pd.DataFrame({
'name': ['John', 'Emma', 'Alex', 'Sarah'],
'age': [28, 24, 32, 27],
'city': ['New York', 'London', 'Paris', 'Tokyo']
})
# 转换为 SmartDataframe
smart_df = SmartDataframe(df)
# 询问有关数据的问题
response = smart_df.chat("What is the average age?")

SmartDataframe 通过其构造函数接受配置选项：

smart_df = SmartDataframe(df, config={
"llm": llm,                              # LLM 实例
"save_logs": True,                       # 保存对话日志
"verbose": False                         # 打印详细日志
})

2.3 语义信息create

语义层的核心作用是架起原始数据与人类理解之间的桥梁。处理数据时，你通常知道名为"cust_id"的列代表客户标识符，或者"sale_date"列包含交易时间戳。语义层允许你将这些上下文知识直接编码到数据集中，使数据集在分析中变得更有价值。

创建语义层时，PandasAI 会进行广泛验证以确保一致性：

• 名称验证：数据集名称必须小写，用下划线代替空格
• 列类型验证：所有列类型必须来自支持的类型集（string、integer、float、datetime、boolean）
• 视图特定验证：视图必须在所有引用表之间定义正确的关系
• 表达式验证：列中的任何 SQL 表达式都会被解析以确保语法正确

通过提供有意义的上下文帮助 AI 更好地理解您的数据：

2.3.1 dataframe提供语义信息

一种方式：提供描述性名称和描述

pai_df = pai.DataFrame(df)
pai_df.schema.name = "employee_demographics"
pai_df.schema.description = "Demographic information for company employees including age, department, and salary"

更好 - 使用带元数据的 create 函数

dataset = pai.create(path="my-company/employees",df=df,description="Employee demographic data for analysis",columns=[{"name": "age", "description": "Employee age in years"},{"name": "salary", "description": "Annual salary in USD"},{"name": "department", "description": "Department name"}]
)

2.3.2 数据源定义语义信息：SQL 数据库

对于 SQL 数据库，可以直接在数据库表上定义语义层：

sql_table = pai.create(path="company/health-data",description="来自 MySQL 数据库的心脏病数据集",source={"type": "mysql","connection": {"host": "${DB_HOST}","port": 3306,"user": "${DB_USER}","password": "${DB_PASSWORD}","database": "${DB_NAME}"},"table": "heart_data"}
)

2.4 输出格式规范

响应类型旨在处理特定用例：

• String Response: 提供文本分析和解释
• Number Response: 返回计算结果的数值
• DataFrame Response: 保留 pandas DataFrame 的结构和功能
• Chart Response: 处理各种可视化格式和绘图库
• Error Response: 结构化错误处理，提供信息丰富的消息

响应系统是可扩展和类型安全的，确保输出根据其特定要求正确格式化和处理。

2.4.4 Generated Code中间代码检查

您可以检查生成的代码以产生结果：

import pandasai as pai
from pandasai_litellm.litellm import LiteLLM
# Initialize LiteLLM with your OpenAI model
apikey = 'sk-xxxxxxxx'
base_url = 'https://dashscope.aliyuncs.com/compatible-mode/v1'
llm = LiteLLM(base_url = base_url,model="dashscope/qwen-turbo", api_key=apikey)
# Configure PandasAI to use this LLM
pai.config.set({
"llm": llm
})
# 创建示例 DataFrame
df = pai.DataFrame({
"country": ["United States", "United Kingdom", "France", "Germany", "Italy", "Spain", "Canada", "Australia", "Japan", "China"],
"revenue": [5000, 3200, 2900, 4100, 2300, 2100, 2500, 2600, 4500, 7000]
})
# 向您的数据提问
response = df.chat('Which are the top 5 countries by sales?')
print(response)
# 最后输出的代码执行
print(response.last_code_executed)
# 最后输出的变成dict格式
response.to_dict()
# 最后输出变成Json格式
response.to_json()

出来的结果是:

import pandas as pd
sql_query = """SELECT country, revenueFROM table_3196ce98cf3ce3223735e1d61022e9d2ORDER BY revenue DESCLIMIT 5
"""
result_df = execute_sql_query(sql_query)
result = {'type': 'dataframe', 'value': result_df}

2.4.5 图表输出

对于图表响应，您可以将可视化保存到文件：

chart_response = df.chat("Create a scatter plot of age vs salary")
chart_response.save("scatter_plot.png")  # 将图表保存为 PNG

2.5 使用视图

文档来自：https://docs.pandas-ai.com/v3/semantic-layer/views

视图是SQL数据库的一项功能，允许您定义可以在查询中使用的数据逻辑子集。在PandasAI中，您可以在语义层架构中定义视图，以组织和结构化您的数据。当您想要：

• 从多个数据集组合数据
• 创建数据的简化或过滤视图
• 定义不同数据集之间的关系

可以通过YAML配置或使用Python编程来创建视图。

几点原则：

• 互斥性：一个架构不能同时定义表和视图。如果视图为真，则该架构表示视图。
• 列格式：对于视图，所有列必须遵循格式 [table].[column]。关系中的 from 和 to 字段必须遵循 [table].[column] 格式。例如：loans.payment_amount, heart.condition。
• 视图的关系：每个在列中引用的表必须在关系中定义至少一个关系。关系必须在 [table].[column] 格式中指定 from 和 to 属性。关系定义了视图中不同表之间的连接。
• 数据集要求：所有引用的数据集必须在创建视图之前存在。视图中指定的列必须存在于各自的源数据集中。关系中使用的列（from 和 to）必须是兼容类型。

2.5.1 python配置

类似把各种表的关联主键都定义好

import pandasai as pai
# 为电子商务分析系统创建源数据集
# 订单数据集
orders_df = pai.read_csv("orders.csv")
orders_dataset = pai.create(
"myorg/orders",
orders_df,
description="客户订单和交易数据"
)
# 产品数据集
products_df = pai.read_csv("products.csv")
products_dataset = pai.create(
"myorg/products",
products_df,
description="带有类别和定价的产品目录"
)
# 客户数据集
customers_df = pai.read_csv("customers.csv")
customers_dataset = pai.create(
"myorg/customers",
customers_df,
description="客户人口统计和偏好"
)
# 定义数据集之间的关系
view_relations = [
{
"name": "order_to_product",
"description": "将订单与其产品链接",
"from": "orders.product_id",
"to": "products.id"
},
{
"name": "order_to_customer",
"description": "将订单与客户资料链接",
"from": "orders.customer_id",
"to": "customers.id"
}
]
# 选择销售分析视图的相关列
view_columns = [
# 订单详情
"orders.id",
"orders.order_date",
"orders.total_amount",
"orders.status",
# 产品信息
"products.name",
"products.category",
"products.unit_price",
"products.stock_level",
# 客户信息
"customers.segment",
"customers.country",
"customers.join_date"
]
# 创建综合的销售分析视图
sales_view = pai.create(
"myorg/sales-analytics",
description="结合订单、产品和客户信息的统一销售数据视图",
relations=view_relations,
columns=view_columns,
view=True
)

此视图使得强大的分析查询成为可能，例如：

• 按客户细分和产品类别的销售趋势
• 客户购买历史和偏好
• 基于订单模式的库存管理
• 地理销售分布

2.5.2 yaml文件定义

name: table_heart
columns:
- name: parents.id
- name: parents.name
- name: parents.age
- name: children.name
- name: children.age
relations:
- name: parent_to_children
description: 连接父母与其子女的关系
from: parents.id
to: children.id

2.6 AI Dashboards仪表盘

文档地址：https://docs.pandas-ai.com/v3/ai-dashboards
请求：https://app.pandabi.ai/

可支持载入数据源：

2.7 Memory内存存储模块

2.7.1 Memory内存基础模块

from pandasai.helpers.memory import Memory
memory = Memory()#一种添加的方式messages = [("Message 1", True), ("Message 2", False), ("Message 3", True)]for msg, is_user in messages:memory.add(msg, is_user=is_user)
# 另外一种添加的方式
memory.add("Hello", is_user=True)
memory.add("Hi there!", is_user=False)
memory.add("How are you?", is_user=True)
memory.to_openai_messages()
memory.to_json()

memory.to_openai_messages() 和 memory.to_json() 是一致的，可以看到输出的是：

[{'role': 'user', 'message': 'Hello'},{'role': 'assistant', 'message': 'Hi there!'},{'role': 'user', 'message': 'How are you?'}]

2.7.2 agent中的Memory

在agent模块也有：

# 3. 构建 Agent（memory_size=10 启用最近10轮记忆）
agent = Agent([employees_df, salaries_df], memory_size=10)
# 4. 进行对话
response = agent.chat("Who gets paid the most?")
print(response)
# 追问
agent.follow_up("Who gets paid the min?")
# agent的描述 - 可以自行添加，一般都是没有的
agent.description
# 获取最近10轮对话摘要（字符串列表） -
print(agent._state.memory.get_messages())
>>> ['### QUERY\n Who gets paid the most?', '### QUERY\n Who gets paid the min?']
# 获取最近10轮对话完整字符串
print(agent._state.memory.get_conversation())
>>> ### QUERY
>>>  Who gets paid the most?
>>> ### QUERY
>>>  Who gets paid the min?
# 最后执行的代码详情
print(agent._state.last_code_generated)

2.7.3 加载memory成为get_system_prompt

from pandasai.helpers.memory import Memory
memory = Memory()
mem = Memory(agent_description="xyz", memory_size=10)
mem.add("hello world", True)  # 用户发言
mem.add('print("hello world)', False) # 系统发言
mem.add("hello world", True) # 用户发言
print(mem.get_messages())
import pandasai as pai
from pandasai_litellm.litellm import LiteLLM
# Initialize LiteLLM with your OpenAI model
apikey = 'sk-xxx'
base_url = 'https://dashscope.aliyuncs.com/compatible-mode/v1'
llm = LiteLLM(base_url = base_url,model="dashscope/qwen-turbo", api_key=apikey)
llm.get_system_prompt(mem)
pai.config.set({
"llm": llm
})
# 创建示例 DataFrame
df = pai.DataFrame({
"country": ["United States", "United Kingdom", "France", "Germany", "Italy", "Spain", "Canada", "Australia", "Japan", "China"],
"revenue": [5000, 3200, 2900, 4100, 2300, 2100, 2500, 2600, 4500, 7000]
})
# 向您的数据提问
response = df.chat('Which are the top 5 countries by sales?')
print(response)

---

3 训练你的agent

文档：https://docs.pandas-ai.com/v3/agent

你可以训练 PandasAI 以更好地理解你的数据并提高其性能。训练的方法很简单，只需调用 Agent 的 train 方法。

在开始训练 PandasAI 之前，你需要设置你的 PandasAI API 密钥。你可以通过在 https://app.pandabi.ai 注册来生成你的 API 密钥。

import pandasai as pai
pai.api_key.set("your-pai-api-key")

重要的是，你需要设置 API 密钥，否则会出现以下错误：
No vector store provided. Please provide a vector store to train the agent.

3.1 Instructions training 指令训练 (类似RAG)

用于教 PandasAI 如何响应特定查询。你可以提供关于你希望模型如何处理某些类型查询的通用指令，PandasAI 将使用这些指令生成对类似查询的响应。

例如，你可能希望 LLM 知道你公司的财年从四月开始，或者关于你希望如何处理缺失数据的具体方式。或者你可能想教它关于特定的业务规则或数据分析最佳实践，这些都是你组织特有的。

要用指令训练 PandasAI，你可以使用 Agent 的 train 方法，如下所示：

训练默认使用 BambooVectorStore 存储训练数据，并且可以通过 API 密钥访问。

作为替代方案，如果你希望使用本地向量存储（仅限企业用于生产用例），你可以使用 ChromaDB、Qdrant 或 Pinecone 向量存储（请参见下面的示例）。

import pandasai as pai
from pandasai import Agent
pai.api_key.set("your-pai-api-key")
agent = Agent("data.csv")
agent.train(docs="The fiscal year starts in April")
response = agent.chat("What is the total sales for the fiscal year?")
print(response)
# 模型将使用提供的训练信息生成响应

你的训练数据是持久化的，因此你只需训练模型一次。

3.2 Q/A training - 问答对存储

Q/A training 用于教 PandasAI 期望的流程，以回答特定问题，从而增强模型的性能和确定性。LLM 的一个最大挑战是它们不是确定性的，这意味着相同的问题在不同时间可能产生不同的答案。Q/A training 可以帮助减轻这个问题。

要用 Q/A 训练 PandasAI，你可以使用 Agent 的 train 方法，如下所示：

from pandasai import Agent
agent = Agent("data.csv")
# 训练模型
query = "What is the total sales for the current fiscal year?"
# 以下代码作为字符串传递给响应变量
response = '\n'.join(['import pandas as pd','','df = dfs[0]','','# 计算当前财年的总销售额','total_sales = df[df[\'date\'] >= pd.to_datetime(\'today\').replace(month=4, day=1)][\'sales\'].sum()','result = { "type": "number", "value": total_sales }'
])
agent.train(queries=[query], codes=[response])
response = agent.chat("What is the total sales for the last fiscal year?")
print(response)
# 模型将使用提供的训练信息生成响应

同样，在这种情况下，你的训练数据是持久化的，因此你只需训练模型一次。

3.3 本地向量存储训练模型

你可以使用本地的 ChromaDB、Qdrant 或 Pinecone 向量存储。以下是如何操作的：使用本地向量存储需要企业许可证（请查看）。

from pandasai import Agent
from pandasai.ee.vectorstores import ChromaDB
from pandasai.ee.vectorstores import Qdrant
from pandasai.ee.vectorstores import Pinecone
from pandasai.ee.vector_stores import LanceDB
# 实例化向量存储
vector_store = ChromaDB()
# 或者使用 Qdrant
# vector_store = Qdrant()
# 或者使用 LanceDB
vector_store = LanceDB()
# 或者使用 Pinecone
# vector_store = Pinecone(
#     api_key="*****",
#     embedding_function=embedding_function,
#     dimensions=384, # 嵌入模型的维度
# )
# 使用自定义向量存储实例化代理
agent = Agent("data.csv", vectorstore=vector_store)
# 训练模型
query = "What is the total sales for the current fiscal year?"
# 以下代码作为字符串传递给响应变量
response = '\n'.join(['import pandas as pd','','df = dfs[0]','','# 计算当前财年的总销售额','total_sales = df[df[\'date\'] >= pd.to_datetime(\'today\').replace(month=4, day=1)][\'sales\'].sum()','result = { "type": "number", "value": total_sales }'
])
agent.train(queries=[query], codes=[response])
response = agent.chat("What is the total sales for the last fiscal year?")
print(response)
# 模型将使用提供的训练信息生成响应

3.4 使用沙箱环境

为了增强安全性并防止通过提示注入的恶意代码，PandasAI 提供了一个沙箱环境用于代码执行。沙箱在隔离的 Docker 容器中运行你的代码，确保潜在的有害操作被限制。
在使用沙箱之前，你需要在你的机器上安装 Docker 并确保其正在运行。

首先，安装沙箱包：

pip install pandasai-docker

以下是如何使用沙箱与 PandasAI 代理：

from pandasai import Agent
from pandasai_docker import DockerSandbox
# 初始化沙箱
sandbox = DockerSandbox()
sandbox.start()
# 创建带有沙箱的代理
df = pai.read_csv("data.csv")
agent = Agent([df], sandbox=sandbox)
# 与代理聊天 - 代码将在沙箱中运行
response = agent.chat("Calculate the average sales")
# 完成后不要忘记停止沙箱
sandbox.stop()

你可以通过指定自定义名称和 Dockerfile 来定制沙箱环境：

sandbox = DockerSandbox("custom-sandbox-name","/path/to/custom/Dockerfile"
)

沙箱离线工作，为代码执行提供了额外的安全层。当处理不受信任的数据或需要确保代码执行与主系统隔离时，它特别有用。

Custom Head

在某些情况下，你可能希望为对话代理提供自定义数据示例，以提高其理解和响应能力。例如，你可能希望：

• 提供更好的示例，代表你的数据模式
• 避免共享敏感信息
• 通过特定数据场景引导代理
• 你可以通过向代理传递自定义头来实现：

import pandas as pd
import pandasai as pai
# 你的原始数据框
df = pd.DataFrame({'sensitive_id': [1001, 1002, 1003, 1004, 1005],'amount': [150, 200, 300, 400, 500],'category': ['A', 'B', 'A', 'C', 'B']
})
# 创建一个带有匿名数据的自定义头
head_df = pd.DataFrame({'sensitive_id': [1, 2, 3, 4, 5],'amount': [100, 200, 300, 400, 500],'category': ['A', 'B', 'C', 'A', 'B']
})
# 使用自定义头
smart_df = pai.SmartDataframe(df, config={"custom_head": head_df
})

代理将使用你的自定义头，而不是在分析和响应查询时默认的前 5 行数据框。

---

4 Chat 大致使用方法

4.1 chat方法工作流程

当您调用 chat() 方法时，幕后会发生以下情况：

• 代理创建：如果不存在代理，则使用您的数据框和配置创建一个。
• 查询处理：您的自然语言查询与数据框的模式和样本数据一起被处理。
• 代码生成：LLM 根据提供的上下文生成 Python 代码来回答您的问题。
• 代码执行：生成的代码在您的数据框可用的安全环境中执行。
• 响应格式化：结果被格式化并作为用户友好的响应返回。

新的语义数据框支持对话式后续问题：

# 开始对话
response = pai_df.chat("What are the total sales by region?")
print(response)
# 提出后续问题
response = pai_df.follow_up("Which product contributed most to the top region?")
print(response)

4.2 提出具体问题

# 模糊的问题
response = pai_df.chat("Tell me about the data")
# 具体的问题
response = pai_df.chat("What is the average salary by department, and which department has the highest average?")

4.3 适当使用输出类型

当您知道自己想要什么时指定输出类型：

# 当您想要特定数字时
avg_salary = pai_df.chat("What is the average salary?", output_type="number")
# 当您想要过滤数据时
high_earners = pai_df.chat("Show employees with salary above 75000", output_type="dataframe")
# 当您想要可视化时
chart = pai_df.chat("Show salary distribution by department", output_type="plot")

4.4 明智处理大型数据集

对于大型数据集，考虑先采样或过滤：

# 对于非常大的数据集，先使用样本
sample_df = pai_df.sample(1000)  # 使用 1000 个随机行
response = sample_df.chat("What are the main patterns in this data?")
# 或过滤到相关数据
relevant_data = pai_df.chat("Filter to records from the last year", output_type="dataframe")
response = relevant_data.chat("Analyze trends in this filtered data")

5 Agent

5.1 使用agent整合数据+查看历史消息

import pandasai as pai
from pandasai_litellm.litellm import LiteLLM
# Initialize LiteLLM with your OpenAI model
apikey = 'sk-xxxxxx'
base_url = 'https://dashscope.aliyuncs.com/compatible-mode/v1'
llm = LiteLLM(base_url = base_url,model="dashscope/qwen-turbo", api_key=apikey)
# Configure PandasAI to use this LLM
pai.config.set({
"llm": llm
})
from pandasai import Agent
# 用 pandasai 的 DataFrame 包裹 pandas 的 DataFrame
import pandas as pd
employees_data = {
"EmployeeID": [1, 2, 3, 4, 5],
"Name": ["Alice", "Bob", "Charlie", "David", "Olivia"],
"Department": ["HR", "Sales", "IT", "Marketing", "Finance"]
}
salaries_data = {
"EmployeeID": [1, 2, 3, 4, 5],
"Salary": [5000, 6000, 4500, 7000, 5500]
}
# 1. 先用 pandas 读入
employees_df = pd.DataFrame(employees_data)
salaries_df = pd.DataFrame(salaries_data)
# 2. 用 pandasai 的 DataFrame 包装
employees_df = pai.DataFrame(employees_df)
salaries_df = pai.DataFrame(salaries_df)
# 3. 构建 Agent（memory_size=10 启用最近10轮记忆）
agent = Agent([employees_df, salaries_df], memory_size=10)
# 4. 进行对话
response = agent.chat("Who gets paid the most?")
print(response)
# 追问
agent.follow_up("Who gets paid the min?")
# agent的描述 - 可以自行添加，一般都是没有的
agent.description
# 获取最近10轮对话摘要（字符串列表） - 
print(agent._state.memory.get_messages())
>>> ['### QUERY\n Who gets paid the most?', '### QUERY\n Who gets paid the min?']
# 获取最近10轮对话完整字符串
print(agent._state.memory.get_conversation())
>>> ### QUERY
>>>  Who gets paid the most?
>>> ### QUERY
>>>  Who gets paid the min?
# 最后执行的代码详情
print(agent._state.last_code_generated)

显示的是：

# TODO: import the required dependencies
import pandas as pd
# Write code here
def execute_sql_query(sql_query: str) -> pd.DataFrame:"""This method connects to the database, executes the sql query and returns the dataframe"""# This is a placeholder function. In a real scenario, this would connect to a database.pass
# SQL query to find the employee with the highest salary
sql_query = """
SELECT e.Name, s.Salary
FROM table_f429f651884f4941543d85bc5583ea4e e
JOIN table_8a25a04fdd74977afdf9a87b59394611 s ON e.EmployeeID = s.EmployeeID
ORDER BY s.Salary DESC
LIMIT 1
"""
# Execute the query and get the result
result_df = execute_sql_query(sql_query)
# Declare result var
result = {"type": "dataframe","value": result_df
}