# @florentine-ai/api 中文文档 规范地址：https://npmcn.com/package/%40florentine-ai/api/ 版本：1\.0\.0 npm 元数据更新时间：2026-03-09T14:16:11.861Z 中文译文更新时间：2026-11-14T23:54:51.871Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40florentine-ai/api 原文对照：https://npmcn.com/package/%40florentine-ai/api/?lang=original 项目主页：https://florentine.ai/ 源码仓库：https://github.com/florentine-ai/api ## 关键信息（来自 npm 元数据） - 包体积（解压后）：39.1 kB，23 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：3 个 - 首次发布：2025-09-08T17:58:49.911Z - 最新版本发布：2026-03-09T14:16:11.699Z - 近 30 天下载量：10203（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：2（近 12 个月 1 个） ## 中文简介 Node.js API Wrapper for Florentine.ai – 查询 MongoDB & MySQL 自然语言数据库 ## 安装 ```sh npm install @florentine-ai/api ``` 也可以使用：`pnpm add @florentine-ai/api`、`yarn add @florentine-ai/api`、`bun add @florentine-ai/api` ## README # 佛罗伦萨.ai API - 与您的 MongoDB & MySQL 数据交谈 Florentine.ai API 允许您整合 **对您的 MongoDB & MySQL 数据进行自然语言查询** 直接进入您的项目. 问题已转变为 **也可以直接执行和回答的数据库查询** 自然语言. 还有一对夫妇 **额外特性** 例如: - **安全的数据分离** 用于多种租户用途 - **自动计划探索** - **语义矢量搜索/RAG支持** 自动嵌入创建 - **高级搜索支持** - **钥匙的排除** > \[注\] 如果你正在寻找我们的MCP服务器,你可以 [找到这里](https://github.com/florentine-ai/mcp)。 。 。 . ## 目录 - [先决条件](https://npmcn.com/package/%40florentine-ai/api/#readme-prerequisites) - [安装](https://npmcn.com/package/%40florentine-ai/api/#readme-installation) - [认证](https://npmcn.com/package/%40florentine-ai/api/#readme-authentication) - [连接您的 LLM 账户](https://npmcn.com/package/%40florentine-ai/api/#readme-connect-your-llm-account) - [选项1: 在账户中保存您的 LLM 密钥( 建议)](https://npmcn.com/package/%40florentine-ai/api/#readme-option-1-save-your-llm-key-in-your-account-recommended) - [选项2:在 API 请求中提供您的 LLM 密钥](https://npmcn.com/package/%40florentine-ai/api/#readme-option-2-provide-your-llm-key-in-api-requests) - [第一次请求](https://npmcn.com/package/%40florentine-ai/api/#readme-first-request) - [返回类型](https://npmcn.com/package/%40florentine-ai/api/#readme-return-types) - [返回全部三个步骤的示例](https://npmcn.com/package/%40florentine-ai/api/#readme-example-returning-all-three-steps) - [多租户使用的安全数据分离](https://npmcn.com/package/%40florentine-ai/api/#readme-secure-data-separation-for-multi-tenant-usage) - [提供所需投入](https://npmcn.com/package/%40florentine-ai/api/#readme-providing-required-inputs) - [所需输入配置](https://npmcn.com/package/%40florentine-ai/api/#readme-required-inputs-configuration) - [支持的值类型](https://npmcn.com/package/%40florentine-ai/api/#readme-supported-value-types) - [用法实例](https://npmcn.com/package/%40florentine-ai/api/#readme-usage-examples) - [会议](https://npmcn.com/package/%40florentine-ai/api/#readme-sessions) - [错误](https://npmcn.com/package/%40florentine-ai/api/#readme-errors) - [处理客户端错误](https://npmcn.com/package/%40florentine-ai/api/#readme-handle-errors-in-client) - [常见错误](https://npmcn.com/package/%40florentine-ai/api/#readme-common-errors) ## 先决条件 - 节点.js >= v 18.0.0 - Florentine.ai账户(创建 [这里的自由账户](https://app.florentine.ai/signup)(中文(简体) ) - 一个连接的数据库和至少一个分析并激活了您的花旗上的收藏/表格 。 ai 账户 - 一个Florentine.ai API 密钥(您可以在您的 [账户仪表板](https://app.florentine.ai/dashboard)(中文(简体) ) ## 安装 API的详细文档可找到 [在这里,我们的文件](https://docs.florentine.ai/api/overview.html)。 。 。 . ```bash npm install @florentine-ai/api ``` ## 认证 ```ts import { Florentine } from '@florentine-ai/api'; const FlorentineAI = new Florentine({ florentineToken: '' }); ``` ## 连接您的 LLM 账户 佛罗伦萨。 。 **带上自己的钥匙模型**,因此您需要在您的 API 请求中提供 LLM API 密钥( OpenAI, Google, Anthropic, Deepseek) . 您有两个选项可以添加您的 LLM API 密钥 : ### 选项1: 在账户中保存您的 LLM 密钥( 建议) 连接您的 LLM 提供者的最简单方式是将您的 LLM API 密钥保存在您的 [佛罗伦萨.ai仪表板](https://florentine.ai/dashboard)。 。 。 . - 添加您的 API 密钥 - 选择您的 LLM 提供者( OpenAI, Deepseek, Google 或 Anthropic) - 单击保存 ![Add your LLM key](https://docs.florentine.ai/images/api/add_own_llm_key.png) ### 选项2:在 API 请求中提供您的 LLM 密钥 如果你不想在佛罗伦萨储存钥匙的话 ai 账户或想要使用多个 LLM 密钥, 您可以通过您的 API 请求中的密钥 . 添加值为 `llmService` 财务报告和审定财务报表 `llmKey` 至类构造对象: ```ts const FlorentineAI = new Florentine({ florentineToken: '', llmService: '', // one of: "openai", "google", "anthropic", "deepseek" llmKey: '' }); ``` > \[注\] 如果你提供 `llmKey` 在请求中,它将覆盖存储在您的账户中的任何密钥. ## 第一次请求 你现在应该准备好 发送你的第一个API请求! 提出一个可以通过您激活的收集/表格中的数据解答的问题,并将其传递给 `.ask()` 方法 : ```ts const FlorentineAI = new Florentine({ florentineToken: '' }); const res = await FlorentineAI.ask({ question: '', sessionId: 'FIRST_REQUEST' }); ``` 默认情况下 **API 返回原始查询结果**返回类型可以通过 `returnTypes`。 。 。 . 想象一个 `tabletennis` 用于记录两个玩家匹配结果的收藏. 如果我问问题 `Who won the last match?` 答案可能与此类似: ```json { "answer": "Frank won the last match. According to our records, he emerged as the winner, highlighting his strong performance in that game." } ``` ## 返回类型 在背景中,每个请求都有三个步骤: 1. **查询生成**:这个问题被转换为数据库查询(MongoDB聚合管或MySQL查询). 2. **查询执行**: 使用您提供的连接字符串查询数据库. 3. **答案生成**:结构化的结果被转化为自然语言的答案. 在您的 Florentine.ai 账户中配置了默认返回类型 。 您可以通过指定一个 `returnTypes` 组合 : | `returnTypes` 数值 | 说明 | 预期反应关键 | | --- | --- | --- | | `"query"` | 返回生成的数据库查询、所使用的数据库和收集/表格、0至10级的置信分和数据库类型(`"mongodb"` 或者说 `"mysql"`) (中文(简体) ). | `confidence`, (中文(简体) ), `database`, (中文(简体) ), `collection`, (中文(简体) ), `query`, (中文(简体) ), `databaseType` | | `"result"` | 返回已执行查询的原始查询结果 . | `result` | | `"answer"` | 返回基于已执行查询结果的自然语言响应. | `answer` | ### 返回全部三个步骤的示例 让我们想象一下 `tabletennis` 实例 [第一次请求](https://npmcn.com/package/%40florentine-ai/api/#readme-first-request) 再一次. 三个步骤都这样 ```ts const res = await FlorentineAI.ask({ question: 'Who won the last match?', returnTypes: ['query', 'result', 'answer'] }); ``` 反应是这样的: ```json { "database": "samples", "collection": "tabletennis", "databaseType": "mongodb", "query": [ { "$sort": { "year": -1, "matchInYear": -1 } }, { "$limit": 1 }, { "$project": { "winner": { "$cond": { "if": { "$eq": ["$matchwinner", "home"] }, "then": "$players.home", "else": "$players.away" } } } } ], "result": [{ "_id": "67d352056d3ef0f2281524cf", "winner": "Frank" }], "answer": "Frank won the last match. According to our records, he emerged as the winner, highlighting his strong performance in that game." } ``` ## 多租户使用的安全数据分离 您可以启用 **安全数据分离** 通过确保查询 **基于提供值的过滤数据** 我们称之为 `Required Inputs`。 。 。 . 这些价值是: **添加到查询中** 由 Florentine.ai 转换层 **在 LLM 生成查询后**因此 **Florentine.ai 可以保证每个用户只获取他有资格获取的数据**。 。 。 . 键被定义为 `Required Input` 请参看 [官方文件中的章节](https://docs.florentine.ai/features/required-inputs.html) 如何做到这一点. ### 提供所需投入 在 a 内提供所需的输入 `requiredInputs` 以 `keyPath` 财务报告和审定财务报表 `value` 对于您设定为必需输入的每个密钥, 并添加到 `.ask()` 方法 : ```ts const res = await FlorentineAI.ask({ question: 'What is the revenue of my products this year?', requiredInputs: [ { keyPath: 'accountId', value: '507f1f77bcf86cd799439011' } ] }); ``` 您也可提供 `database` (单位:千美元) `collections` 阵列,如果您有相同的输入要求 `keyPath` 在多个收藏/表格中,但不同 `value` 用于收集/表格: ```ts const res = await FlorentineAI.ask({ question: 'Whats the current monthly rent of my tenants?', requiredInputs: [ { keyPath: 'name', value: 'Sesame Street', database: 'rentals', collections: ['houses'] }, { keyPath: 'name', value: { $in: ['Ernie', 'Bert'] }, database: 'rentals', collections: ['tenants'] } ] }); ``` ### 所需输入配置 | 外地 | 需求 | 类型 | 说明 | 制约因素 | | --- | --- | --- | --- | --- | | `keyPath` | 对 | 字符串 | 应过滤的去字段路径 . | 必须是有效的密钥路径 . | | `value` | 对 | 任意 | 要过滤的值( 类型, 见 [支持的值类型](https://npmcn.com/package/%40florentine-ai/api/#readme-supported-value-types)) (中文(简体) ). | 必须匹配字段的类型( String, ObjectId, Boolean, 数字, 或 Date) . | | `database` | 没有 | 字符串 | 包含要过滤的收藏的数据库 . | 如果 `collections` 提供. | | `collections` | 没有 | `Array` | 数据库中用于应用过滤器的具体收藏/表格. | 必须包含至少一个收藏/表 . | ### 支持的值类型 基于按键的值类型,您对您可以提供什么有不同的选项 `Required Input` 值 : | 类型 | 格式示例 | 支持的运算符 | 页:1 | | --- | --- | --- | --- | | `String` 或者说 `Array` | `"text"` `{ $in: ["text1", "text2"] }` | `$in` | 案件敏感. | | `ObjectId` 或者说 `Array` | `"507f191e810c19729de860ea"` `{ $in: ["507f191e810c19729de860ea", "507f191e810c19729de860eb"] }` | `$in` | 作为绳索提供. | | `Boolean` | `true`编号 :`false` | —— 说 | 只有准确的数值. | | `Number` 或者说 `Array` | `42` `{ $gt: 10, $lte: 100 }` `{ $in: [1, 2, 3] }` `{ $in: [{$gte:1}, {$lt:10}] }` | `$gt`, (中文(简体) ), `$gte`, (中文(简体) ), `$lt`, (中文(简体) ), `$lte`, (中文(简体) ), `$in` | 支持小数. | | `Date` 或者说 `Array` | `"2024-01-01T00:00:00Z"` (UTC) (中文(简体) ) `"2024-01-01T00:00:00-05:00"`(时区平分) | `$gt`, (中文(简体) ), `$gte`, (中文(简体) ), `$lt`, (中文(简体) ), `$lte`, (中文(简体) ), `$in` | ISO 8601格式. | ### 用法实例 **示例类型 :** `String` **使用大小写 :** 用户只能查看他经常玩的玩家的统计数据. **解决方案 :** 将玩家名限制在由4名玩家组成的组内访问. ```ts const res = await FlorentineAI.ask({ question: 'Which player had the most wins?', requiredInputs: [ { keyPath: 'name', value: { $in: ['Megan', 'Frank', 'Jen', 'Bob'] } } ] }); ``` **示例类型 :** `ObjectId` **使用大小写 :** 用户只能看到自己产品的收入. **解决方案 :** 限制账户访问一个特定账户. ```ts const res = await FlorentineAI.ask({ question: 'Whats the revenue of my products?', requiredInputs: [ { keyPath: 'accountId', value: '507f1f77bcf86cd799439011' } ] }); ``` **示例类型 :** `Boolean` **使用大小写 :** 对客户的每一次分析只能对付费客户进行. **解决方案 :** 限制Paid Account只向付费客户开放. ```ts const res = await FlorentineAI.ask({ question: 'How many customers registered in the last year?', requiredInputs: [ { keyPath: 'isPaidAccount', value: true } ] }); ``` **示例类型 :** `Number` **使用大小写 :** 只应允许雇员看到低于某一数额的付款信息. **解决方案 :** 限制获得金额低于10 000美元的付款. ```ts const res = await FlorentineAI.ask({ question: 'List all payments we received.', requiredInputs: [ { keyPath: 'amount', value: { $lt: 10000 } } ] }); ``` **示例类型 :** `Date` **使用大小写 :** 对财务数据的分析只应包括一年. **解决方案 :** 2024年通过交易限制所有交易Date访问. ```ts const res = await FlorentineAI.ask({ question: 'What was our revenue, profit and margin per month?', requiredInputs: [ { keyPath: 'transactionDate', value: { $gte: '2023-01-01T00:00:00Z', $lt: '2024-01-01T00:00:00Z' } } ] }); ``` ## 会议 **会议** 允许 Florentine.ai 使用 **启用服务器侧聊天历史**。仅仅提供 `sessionId` 像这样的字符串 : ```ts const res = await FlorentineAI.ask({ question: 'What is the revenue of my products this year?', sessionId: '' }); ``` 强制会话,除非您 **禁用服务器侧聊天历史** 设置 `withHistory` 改为 `false` 构造器内 : ```ts const FlorentineAI = new Florentine({ florentineToken: '', withHistory: false }); ``` > \[注\] 强烈建议采用 `sessionId` 进行有意义的多回合对话. ## 错误 Florentine.ai API的所有出错都遵循这个一致的JSON结构: ```json { "error": { "name": "FlorentineApiError", "statusCode": 401, "message": "Please provide your Florentine API key. You can find it in your account settings: https://florentine.ai/settings", "errorCode": "NO_TOKEN", "requestId": "abc123" } } ``` | 外地 | 类型 | 说明 | | --- | --- | --- | | `name` | 字符串 | 错误类名称( 如 ). `FlorentineApiError`, (中文(简体) ), `FlorentineConnectionError`(中文(简体) ) | | `statusCode` | 编号 | HTTP状态代码(例如. `400`, (中文(简体) ), `500`(中文(简体) ) | | `message` | 字符串 | 对出错的解释 | | `errorCode` | 字符串 | 错误标识符(例如). `NO_TOKEN`, (中文(简体) ), `INVALID_LLM_KEY`(中文(简体) ) | | `requestId` | 字符串 | 此请求的唯一 ID (帮助支持和调试) | ### 处理客户端错误 API 错误会作为 JavaScript 错误类自动抛出 : ```ts import { Florentine, FlorentineApiError } from '@florentine-ai/api'; try { const FlorentineAI = new Florentine({}); const res: TFlorentineReturnOutput = await FlorentineAI.ask({ question: 'Who is Florentine?' }); } catch (err) { if (err instanceof FlorentineApiError) { console.error(err.message); // "Please provide your Florentine API key." console.error(err.statusCode); // 401 console.error(err.errorCode); // "NO_TOKEN" console.error(err.requestId); // "abc123" } } ``` 所有客户端错误扩展 `FlorentineError` 类,这样您就可以捕捉到所有与客户端相关的错误 : ```ts if (err instanceof FlorentineError) { // Catches all florentine npm package errors } ``` ### 常见错误 | 错误类型 | 错误代码 | 含义 | | --- | --- | --- | | `FlorentineApiError` | `NO_TOKEN` | 缺少 Florentine API 密钥 | | `FlorentineApiError` | `INVALID_TOKEN` | Florentine API 密钥无效 | | `FlorentineApiError` | `LLM_KEY_WITHOUT_SERVICE` | 你必须提供 `llmService` 若为 `llmKey` 定义 | | `FlorentineApiError` | `LLM_SERVICE_WITHOUT_KEY` | 你必须提供 `llmKey` 若为 `llmService` 定义 | | `FlorentineApiError` | `INVALID_LLM_SERVICE` | 无效 `llmService` 提供 | | `FlorentineApiError` | `NO_OWN_LLM_KEY` | 您需要提供自己的 llm 密钥 | | `FlorentineApiError` | `NO_ACTIVE_COLLECTIONS` | 没有激活账户的收款/表格 | | `FlorentineApiError` | `MISSING_REQUIRED_INPUT` | 缺少必要的输入 | | `FlorentineApiError` | `INVALID_REQUIRED_INPUT` | 需要的输入无效 | | `FlorentineApiError` | `INVALID_REQUIRED_INPUT_FORMAT` | 需要的输入格式无效 | | `FlorentineApiError` | `NO_QUESTION` | 问题不见了 | | `FlorentineApiError` | `EXECUTION_FAILURE` | 创建查询执行失败 | | `FlorentineApiError` | `NO_CHAT_ID` | 需要历史聊天代号, 但缺少 | | `FlorentineLLMError` | `API_KEY_ISSUE` | LLM API 密钥无效 | | `FlorentineLLMError` | `NO_RETURN` | Florentine.ai 没有收到有效的 LLM 返回 | | `FlorentineLLMError` | `RATE_LIMIT_EXCEEDED` | LLM 语言 请求大小太大 | | `FlorentineApiError` | `TOO_MANY_TOKENS` | 查询提示超过了 LLM 模型的最大符号 | | `FlorentineConnectionError` | `CONNECTION_REFUSED` | 无法连接数据库查询执行 | | `FlorentineCollectionError` | `NO_EXECUTION` | 无法执行已创建的查询 | | `FlorentinePipelineError` | `MODIFICATION_FAILED` | 修改查询管道失败 | | `FlorentineUsageError` | `LIMIT_REACHED` | 你计划中所有的API请求都耗尽了 | | `FlorentineUnknownError` | `UNKNOWN_ERROR` | 所有发生未知错误 | ## 常见问题 ### @florentine-ai/api 是什么？ Node\.js API Wrapper for Florentine\.ai – 查询 MongoDB & MySQL 自然语言数据库 ### 如何安装 @florentine-ai/api？ 在项目目录运行 npm install @florentine-ai/api，或使用 pnpm add / yarn add / bun add。 ### @florentine-ai/api 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @florentine-ai/api 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @florentine-ai/api 可以商用吗？ @florentine-ai/api 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @florentine-ai/api 的下载量有多少？ 根据 npm 官方下载统计，@florentine-ai/api 在 2026/10/15 – 2026/11/13 这 30 天内被下载 10,203 次，日均约 340 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @florentine-ai/api 还在维护吗？ 最新版本 1\.0\.0 发布于 2026/03/09（8 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 1 个；首次发布于 2025/09/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。