CSVBrain

版本：1.0.3
作者：@TheShadowRose
许可证：MIT

描述

加载 CSV 文件，并使用纯英文提问。通过 Anthropic、OpenAI 或本地 Ollama 提供 AI 驱动的自然语言查询能力，无需编写 SQL。

CSVBrain 解析 CSV 文件（支持逗号、分号或制表符分隔），自动分析数据结构，并支持通过结构化筛选条件或 AI 驱动的纯英文问题来查询数据。

特性

• CSV 加载 — 自动检测分隔符（逗号、分号、制表符），支持带引号字段及转义引号。
• 数据概要分析 — 为每列提供即时统计信息：总行数、缺失值数量、唯一值数量；数值列额外提供最小值、最大值与平均值。
• 结构化查询 — 支持对数据进行筛选、排序、限制返回行数以及聚合操作。
• 自然语言提问 — 使用纯英文向数据提问。AI 会基于数据集的结构、类型与统计信息，返回包含具体数值的准确答案。
• 多 AI 提供商支持 — 可将问题路由至 Anthropic（Claude）、OpenAI（GPT）或本地 Ollama 模型，仅需修改模型前缀即可切换。
• 零依赖 — 纯 Node.js 实现，无需任何 npm 包；HTTP 请求使用内置 https/http 模块。

安装

将 src/csv-brain.js 复制到您的项目中。

const { CSVBrain } = require('./src/csv-brain');

快速开始

const { CSVBrain } = require('./src/csv-brain');

const brain = new CSVBrain();
const info = brain.load('sales.csv');
console.log(info);
// { rows: 1200, columns: 8, types: { month: 'text', revenue: 'number', ... } }

// 分析数据概要
const stats = brain.profile();
console.log(stats.revenue);
// { type: 'number', count: 1200, missing: 0, unique: 987, min: 12.5, max: 94200, avg: 8450.32 }

// 使用纯英文提问
const result = await brain.ask('What was our best month for revenue?');
console.log(result.answer);
// "Based on the data, March had the highest total revenue at $94,200."
console.log(result.model);
// "anthropic/claude-haiku-4-5"

API

new CSVBrain(options?)

创建新实例。

const brain = new CSVBrain({ model: 'openai/gpt-4o-mini' });

load(filePath, options?)

同步加载 CSV 文件。

返回值：{ rows: number, columns: number, types: object }

const info = brain.load('data.csv');
const info2 = brain.load('data.tsv', { delimiter: 't' });

profile()

获取所有列的统计概要信息。

返回值：以列名为键的对象，每个键对应一个对象，包含 type、count、missing、unique 字段；数值列额外包含 min、max、avg 字段。

const stats = brain.profile();
console.log(stats);

query(options)

对已加载的数据执行结构化查询。

// 筛选并排序
const topSales = brain.query({
  filter: { column: 'revenue', operator: '>', value: 10000 },
  sort: { column: 'revenue', order: 'desc' },
  limit: 10
});

// 聚合
const totals = brain.query({
  aggregate: { column: 'revenue' }
});
console.log(totals);
// { count: 1200, sum: 10140384, avg: 8450.32, min: 12.5, max: 94200 }

async ask(question, options?)

就您的数据提出自然语言问题。需配置 AI 提供商 API 密钥（或运行本地 Ollama）。

返回值：{ answer: string, data: any, query: object|null, model: string }

// 使用 Anthropic（默认）
// 需设置 ANTHROPIC_API_KEY 环境变量
const result = await brain.ask('Which product category has the highest average price?');
console.log(result.answer);
// "Electronics has the highest average price at $342.50, followed by Appliances at $289.00."

// 使用 OpenAI
// 需设置 OPENAI_API_KEY 环境变量
const result2 = await brain.ask('How many orders were placed in Q4?', {
  model: 'openai/gpt-4o-mini'
});

// 使用本地 Ollama（无需 API 密钥）
const result3 = await brain.ask('Summarize the sales trends', {
  model: 'ollama/llama3'
});

AI 提供商配置

Anthropic（Claude）

将 API 密钥设为环境变量：

export ANTHROPIC_API_KEY="sk-ant-..."

可用模型：anthropic/claude-haiku-4-5、anthropic/claude-sonnet-4-20250514 等。

OpenAI（GPT）

export OPENAI_API_KEY="sk-..."

可用模型：openai/gpt-4o-mini、openai/gpt-4o 等。

Ollama（本地）

无需 API 密钥。只需在本地运行 Ollama：

ollama serve
ollama pull llama3

可用模型：ollama/llama3、ollama/mistral 等。

可选：自定义主机地址：

export OLLAMA_HOST="http://192.168.1.100:11434"

错误处理

若 AI 提供商不可用，ask() 将返回优雅的错误信息而非抛出异常：

const result = await brain.ask('What is the trend?');
if (result.answer.startsWith('AI unavailable:')) {
  console.log('Falling back to manual query...');
  const data = brain.query({ sort: { column: 'date', order: 'asc' } });
}

支持的文件格式

• CSV — 逗号分隔值（.csv）
• TSV — 制表符分隔值（.tsv、.txt）
• 分号分隔 — 常见于欧洲地区导出的数据

分隔符将自动从首行检测，也可手动指定。

注意：Excel 文件（.xlsx、.xls）不支持。请先将电子表格导出为 CSV 格式。

限制

• 文件以同步方式完整加载至内存。超大文件（100MB+）可能导致性能下降。
• AI 回答质量取决于所选模型的能力与上下文窗口大小。仅向 AI 发送列概要信息与前 5 行样本数据，而非全部数据集。
• 不支持流式响应。AI 的完整响应将一次性返回。
• 无内置导出功能。请结合 query() 返回结果，自行实现文件写入逻辑。

免责声明

CSVBrain 按“原样”提供，遵循 MIT 许可证。AI 生成的答案可能并非始终准确，请务必对关键数据分析结果进行人工复核。调用 AI 接口可能产生相应服务商费用。

支持

• 问题反馈：github.com/TheShadowRose/CSVBrain/issues
• 作者：@TheShadowRose