Python — AVA 文档

配置

const ava = new AVA({
  llm: { model: 'YOUR_MODEL', apiKey: process.env.OPENAI_API_KEY },
  engine: { type: 'python', queryTimeoutMs: 30000 },
});

本地执行需要 python3 和 pandas。读取 Excel、Parquet 等文件格式时，可能还需要安装 pandas 的可选依赖。

引擎选项

将 engine.type 设为 python。engine 接受的全部额外字段如下。

字段	类型	必填	含义与默认值
`execute`	`(code: string) => Promise<ExecutionResult>`	否	用自定义环境替换本地 python3 执行。本地执行没有沙箱；回调应运行完整 Python 脚本，将其 JSON 输出作为 ExecutionResult 返回。脚本已包含数据加载和结果限制；远程执行超时需另行配置。
`queryTimeoutMs`	`number`	否	客户端等待上限及本地进程执行时限，默认 30000 毫秒。

支持的数据源

支持内存 CSV、JSON，以及 CSV、JSON、Excel、Parquet 文件；文件可以是本地路径或 HTTP(S) URL。不支持文本提取和数据库源。source() 保存经过验证的配置，实际读取发生在执行查询或计算元数据时；每次查询都会重新加载输入。

查询中的变量

pd 指向 pandas；DataFrame 按 schema 表名存放在 tables 中。只有一张表时，还可直接使用 df。最终值需赋给 result。

const result = await ava.query("result = df.groupby('region', as_index=False)['revenue'].sum()");

DataFrame 和 Series 的索引不会自动返回；索引值有业务含义时，请使用 reset_index()。每次执行都从原始输入重新开始，修改和变量不会跨调用保留。

提供 Python 执行器

你可以保留 AVA 的 Python 查询生成与数据源处理逻辑，只替换完整脚本的运行位置：

import { AVA, type ExecutionResult } from '@antv/ava';
 
const ava = new AVA({
  llm: { model: 'YOUR_MODEL', apiKey: process.env.OPENAI_API_KEY },
  engine: {
    type: 'python',
    queryTimeoutMs: 30000,
    execute: async (code: string): Promise<ExecutionResult> => {
      const response = await fetch('https://YOUR_EXECUTOR/run', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ code }),
        signal: AbortSignal.timeout(30000),
      });
      if (!response.ok) throw new Error(`Python execution failed: ${response.status}`);
      return (await response.json()) as ExecutionResult;
    },
  },
});

YOUR_EXECUTOR 是你自己的应用服务，不是 AVA 提供的端点。它需要使用 Python 和 pandas 执行传入脚本，解析 JSON 输出，并返回 ExecutionResult。请在服务边界验证响应。脚本中的本地文件路径也必须在执行器环境中存在；也可以改用内存数据或执行器可访问的 URL。

回调参数与结果	类型	必填	含义
`code`	`string`	是	包含数据加载和结果限制的完整脚本。
返回的 Promise	`Promise<ExecutionResult>`	是	成功时返回 `schema`、`data` 和适用的截断信息；失败时拒绝 Promise。

完整引擎字段见引擎选项，返回结构见执行结果。超时与资源限制应由服务自身执行；中止 HTTP 请求只会结束客户端等待。