# @cap-js/ai 中文文档

规范地址：https://npmcn.com/package/%40cap-js/ai/

版本：1\.3\.0
npm 元数据更新时间：2026-10-26T11:13:43.192Z
中文译文更新时间：2026-11-09T01:38:33.654Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cap-js/ai
原文对照：https://npmcn.com/package/%40cap-js/ai/?lang=original
项目主页：https://cap.cloud.sap/
源码仓库：https://github.com/cap-js/ai

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：219 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- peer 依赖：@sap/cds \>=9
- 首次发布：2026-04-27T23:09:50.263Z
- 最新版本发布：2026-10-26T11:13:39.303Z
- 近 30 天下载量：232116（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

人工智能能力的CAP cds-plugin

## 安装

```sh
npm install @cap-js/ai
```

也可以使用：`pnpm add @cap-js/ai`、`yarn add @cap-js/ai`、`bun add @cap-js/ai`

## README

[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/ai)](https://api.reuse.software/info/github.com/cap-js/ai)

# 节点的 CAP AI 插件

`@cap-js/ai` 增加由SAP AI Core提供动力的UI建议,简化对SAP AI Core资源的访问,并给CAP应用程序提供向量嵌入支持.

## 建议

该插件将SAP-RPT-1的建议添加到有草稿功能的实体. 自动包含有值帮助的字段 :

```cds
@odata.draft.enabled
entity Books {
  key ID    : Integer;
      title : String;
      genre : Association to Genres;
      price : Decimal;
}

annotate Genres with @cds.odata.valuelist;
```

![Recommendations as default values](https://npmcn.com/package/%40cap-js/ai/_assets/recommendation-default.png)

使用 `@UI.RecommendationState` 选择进入或退出的单个字段:

```cds
annotate Books with {
  genre @UI.RecommendationState: 0;
  price @UI.RecommendationState;
}
```

生产部署需要 [SAP AI 核心](https://help.sap.com/docs/sap-ai-core) 服务约束。 没有一个,地方发展就使用模拟执行进行UI烟雾测试. 见 [建议](https://npmcn.com/package/%40cap-js/ai/.docs/recommendations.md) 用于回归目标、请求行为、数据处理和部署生命周期.

## SAP AI 核心

插件提供了一个 `AICore` 管理资源组、部署和配置的联合呼吁程序服务:

```js
const aiCore = await cds.connect.to('AICore');
const { resourceGroups, deployments } = aiCore.entities;

const groups = await aiCore.run(SELECT.from(resourceGroups));
await aiCore.stop(deployments, { id: '<deployment id>' });
```

见 [SAP AI 核心整合](https://npmcn.com/package/%40cap-js/ai/.docs/ai-core.md) 用于设置、支持查询、帮助方法以及多版本.

## 本地向量嵌入 SQLite (实验)

> \[尖叫声\] SQLite扩展,本地向量嵌入,本地模型管理,以及相关的工具化都是当地发展的实验设施. 预计会发生中断变化,包括由SQLite同步功能接口和本地模型管理所引发的变化. 使用SAP HANA的向量引擎进行生产向量工作量.

`@cap-js/ai` 重定向标准 `sqlite` 数据库,以便 `VECTOR_EMBEDDING` 而矢量函数在本地运行与真实 [国家统计局](https://onnx.ai/) 型号——没有外部服务,也没有代码对SAP HANA的修改. 这使得您可以在SQLite上开发并测试语义搜索. 以下搜索 [书店](https://github.com/capire/bookshop)书的描述意义.

1.  安装本地发展依赖:
    
    ```sh
    npm add -D @cap-js/ai @cap-js/sqlite@^3.1 @huggingface/hub \
      @huggingface/tokenizers onnxruntime-node
    ```
    
    这需要 `@sap/cds` `^10.1` 财务报告和审定财务报表 `@cap-js/sqlite` `^3.1` (软件包的其他能力仍然支持) `@sap/cds` 9. 不需要配置:标准 `sqlite` 财务报告和审定财务报表 `sqlite:memory` 数据库自动拾取本地执行.
    
2.  将搜索显示为 OData 函数。 它按照嵌入式搜索短语与每本书嵌入式描述的相近性对书籍进行排序:
    
    ```cds
    using { sap.capire.bookshop.Books } from '@capire/bookshop';
    
    service SearchService {
      function searchBooks(phrase : String) returns array of {
        title : String;
        relevance : Double;
      };
    }
    ```
    
    ```js
    const cds = require('@sap/cds')
    
    module.exports = class SearchService extends cds.ApplicationService { init() {
      this.on('searchBooks', ({ data: { phrase } }) =>
        SELECT.from('sap.capire.bookshop.Books')
          .columns`title, cosine_similarity(
            vector_embedding(descr, 'DOCUMENT', 'SAP_GXY.20250407'),
            vector_embedding(${phrase}, 'QUERY', 'SAP_GXY.20250407')) as relevance`
          .orderBy`relevance desc`
      )
      return super.init()
    }}
    ```
    
    SQLite上忽略了模型名称——使用了本地配置的模型,并在SAP HANA上获得荣耀,因此在两者上相同的查询运行不变. 这把每本书的描述都嵌入在每个请求上;对于重复的搜索,坚持嵌入(见 [本地向量嵌入](https://npmcn.com/package/%40cap-js/ai/.docs/vector-embeddings.md)) (中文(简体) ).
    
3.  运行应用程序并调用函数 :
    
    ```sh
    cds watch
    ```
    
    在另一个终端:
    
    ```sh
    curl "http://localhost:4004/odata/v4/search/searchBooks(phrase='a%20haunting%20poem%20about%20lost%20love')"
    ```
    

`@cap-js/ai` 查找工程中配置的模型 `.cds/models` 首先,然后输入 `~/.cds/models`。如果丢失,则启动警告,下载到 `~/.cds/models` ,并初始化; 后期启动和其他项目再使用缓存。 下载块启动,所以预安装大型模型 `npx @cap-js/ai install-model <model>` 以避免慢步或被困住 该函数返回按语句相关性排序的书.

当前默认值是 [`sentence-transformers/all-MiniLM-L6-v2`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2),仅作为匹配句式-等同性任务,ONNX格式,以及Apache-2.0许可证的最下載量相當小的模型被选择. 这不是一项建议,在试验阶段可能会改变 `cds.requires.db.embedding.model` 把它钉上 在 [与 ONNX 工艺品的 Apache-2.0 句子相似性模型的趋势](https://huggingface.co/models?pipeline_tag=sentence-similarity&library=onnx&license=license:apache-2.0&sort=trending),然后用所提供的工具验证您的选择.

见 [选择模型](https://npmcn.com/package/%40cap-js/ai/.docs/model-selection.md) 财务报告和审定财务报表 [本地向量嵌入](https://npmcn.com/package/%40cap-js/ai/.docs/vector-embeddings.md) 用于兼容性检查、明确或共享提供、运行时间行为和限制.

## 高级

-   [建议](https://npmcn.com/package/%40cap-js/ai/.docs/recommendations.md) 生成的服务形状、预测背景、回归目标和生命周期
-   [SAP AI 核心整合](https://npmcn.com/package/%40cap-js/ai/.docs/ai-core.md) 约束性、多期性、辅助操作和辅助方法
-   [本地向量嵌入](https://npmcn.com/package/%40cap-js/ai/.docs/vector-embeddings.md) —— SQLite 类型,模式提供, SQL 函数行为,以及信任边界
-   [选择模型](https://npmcn.com/package/%40cap-js/ai/.docs/model-selection.md) ——牵引面部滤波器,相容性要求和大小取舍
-   [当地知识图](https://npmcn.com/package/%40cap-js/ai/.docs/knowledge-graph.md) 实验性 `SPARQL_EXECUTE` 财务报告和审定财务报表 `sparql_table` 支助

## 测试本地插件

样本应用在 `tests/bookshop`。 。 。 .

```sh
npm test
```

集成测试需要SAP AI Core绑定:

```sh
cds bind ai-core -2 <your-ai-core-service-instance>
npm run test:hybrid
```

## 支助、反馈和贡献

此项目欢迎特性请求、 错误报告和通过 [GitHub 问题](https://github.com/cap-js/ai/issues)见 [贡献准则](https://npmcn.com/package/%40cap-js/ai/CONTRIBUTING.md) 为发展信息服务.

## 警卫

通过项目报告潜在的安全问题 [安全政策](https://github.com/cap-js/ai/security/policy)而不是通过公共问题.

## 行为守则

参加该项目须遵守以下规定: [行为守则](https://github.com/cap-js/.github/blob/main/CODE_OF_CONDUCT.md)。 。 。 .

## 许可证发放

版权2026 SAP SE或SAP附属公司和Ai撰稿人。 见 [自由主义](https://npmcn.com/package/%40cap-js/ai/LICENSE) 编辑 [实际报告](https://api.reuse.software/info/github.com/cap-js/ai)。 。 。 .

## 常见问题

### @cap-js/ai 是什么？

人工智能能力的CAP cds-plugin

### 如何安装 @cap-js/ai？

在项目目录运行 npm install @cap-js/ai，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@sap/cds（\>=9）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 cds-ai，可以用 npx cds-ai 直接运行。

### @cap-js/ai 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cap-js\_\_ai 是否存在。

### @cap-js/ai 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cap-js/ai 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cap-js/ai 可以商用吗？

@cap-js/ai 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cap-js/ai 的下载量有多少？

根据 npm 官方下载统计，@cap-js/ai 在 2026/10/09 – 2026/11/07 这 30 天内被下载 232,116 次，日均约 7,737 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cap-js/ai 还在维护吗？

最新版本 1\.3\.0 发布于 2026/10/26（13 天前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/04/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。