# @crvouga/mockingbird-service-llamacloud 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-llamacloud/

版本：3\.11\.0
npm 元数据更新时间：2026-11-11T02:23:37.681Z
中文译文更新时间：2026-11-11T02:29:34.951Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-llamacloud
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-llamacloud/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/llamacloud#readme
源码仓库：https://github.com/crvouga/mockingbird

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

- 包体积（解压后）：4.4 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-09-22T23:55:17.698Z
- 最新版本发布：2026-11-11T02:23:37.333Z
- 近 30 天下载量：16221（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

LlamaCloud平台 API 的状态仿真器:项目和管线检查,管线文件,以及确定性(标注或期限重叠)取回,对照官方 lama cloud services SDK进行校验.

## 安装

```sh
npm install @crvouga/mockingbird-service-llamacloud
```

也可以使用：`pnpm add @crvouga/mockingbird-service-llamacloud`、`yarn add @crvouga/mockingbird-service-llamacloud`、`bun add @crvouga/mockingbird-service-llamacloud`

## README

# @crvouga/ mockingbird-service-lamacloud (中文(简体) )

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

国家模拟器 **拉玛克卢德** 用于测试套件的平台 API(LlamaIndex管理索引): 项目和管道查询、管道文件(清单、获取、插入、更新、删除),以及 检索。 检索是决定性的:当测试设定一个时,一个脚本答案,否则就是 周期重叠对编审中文件的排名。 聊天知识工具 (单位:千美元)`search_health_knowledge`, (中文(简体) ), `search_faq`)和EMR聊天人-admin 知识 CRUD 运行对手 它没有供应商账户,没有嵌入,也没有决定.

-   行动范围: [支助](https://github.com/crvouga/mockingbird/blob/main/packages/service/llamacloud/SUPPORT.md)
-   合同`openapi.yaml`()由Python客户端的官方电线模型手写 我们的后端适配器.

## 安装

```bash
npm install -D @crvouga/mockingbird-service-llamacloud
```

仅限无害环境管理。 节点 22或 Bun 1.2. 无土生属地. 给它服务 `npx mockingbird-llamacloud serve`, (中文(简体) ), `createServer` 从 `./server` (节点),或 `createRuntime` 与 任何获取服务器.

## 使用量

```bash
npx mockingbird-llamacloud serve --port 8805 --index acme-member-kb-v1 --project Default
```

对准应用程序:

| 消费者 | 设置 |
| --- | --- |
| 后端 `LlamaCloudKnowledgeAdapter` | `LLAMACLOUD_BASE_URL=http://127.0.0.1:8805/api/v1` (接缝) **G-L1级**:适配器硬码 `https://api.cloud.llamaindex.ai/api/v1` 今天), 加上 `LLAMACLOUD_API_KEY` (任何价值)和 `LLAMACLOUD_INDEX_NAME` 编号 : `LLAMACLOUD_PROJECT_NAME` 匹配种子管道 |
| Python 聊天服务( S)`llama_cloud_services`(中文(简体) ) | `LLAMA_CLOUD_BASE_URL=http://127.0.0.1:8805` (无) `/api/v1`;下面核实,不需要更改代码) |

```ts
import LlamaCloud from "@llamaindex/llama-cloud"
import { createRuntime } from "@crvouga/mockingbird-service-llamacloud"

// Test setup: a pipeline, and what retrieval answers for queries mentioning "apob".
// Anything else is ranked by term overlap over the documents the app upserted.
const emulator = createRuntime({ pipelines: [{ name: "acme-member-kb-v1", projectName: "Default" }] })
await emulator.fetch(
  new Request("http://llamacloud.test/__admin/retrieval", {
    method: "PUT",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      match: { contains: "apob" },
      nodes: [{ text: "ApoB counts atherogenic particles.", score: 0.92, metadata: { file_name: "apob.md" } }],
    }),
  }),
)

// The LlamaCloud SDK your application already uses. Only its fetch changes: requests reach
// the emulator in this process instead of api.cloud.llamaindex.ai.
const llama = new LlamaCloud({
  apiKey: "llx-mockingbird",
  fetch: (url: RequestInfo | URL, init?: RequestInit) => emulator.fetch(new Request(url, init)),
})
const [pipeline] = await llama.pipelines.list({ project_name: "Default", pipeline_name: "acme-member-kb-v1" })
const { retrieval_nodes } = await llama.pipelines.retrieve(pipeline?.id ?? "", { query: "What does ApoB measure?" })
console.log(retrieval_nodes[0]?.node.text, retrieval_nodes[0]?.score) // ApoB counts atherogenic particles. 0.92
```

### 路线

全部在 `Authorization: Bearer <key>` (任何非空密钥,除非 `apiKeys` 已设定). 错误是 FastAPI 形状 : `{"detail": "…"}`,以及422个 `{"detail": [{loc, msg, type}]}`。 。 。 .

| 路线 | 行为 |
| --- | --- |
| `GET /api/v1/projects?project_name=` | 确切名称的项目(`[]` (没有). |
| `GET /api/v1/projects/{id}` | 一个项目,或404个. |
| `GET /api/v1/pipelines?project_name=&project_id=&pipeline_name=&pipeline_type=` | 匹配每个给定过滤器的管道 : `[{id, name, project_id, pipeline_type: "MANAGED", embedding_config, status: "CREATED", …}]`后端过滤器 `project_name` 选择 `name == LLAMACLOUD_INDEX_NAME`。 。 。 . |
| `GET /api/v1/pipelines/{id}` | 一个管道,或404. |
| `POST /api/v1/pipelines/{id}/retrieve` | `{query, dense_similarity_top_k?, …}` → `{pipeline_id, retrieval_nodes: [{node: {id_, text, metadata, extra_info, …}, score}], …}`。上克默认为 5. |
| `GET /api/v1/pipelines/{id}/documents?skip=&limit=` | `[{id, text, metadata, …}]`,最古老的第一. |
| `PUT /api/v1/pipelines/{id}/documents` | 升级 `[{id?, text, metadata}]` 由 id(后端使用 sult;缺失的 id 获得UUID. 回答存储的文件. |
| `POST /api/v1/pipelines/{id}/documents` | 与 PUT (SDK ) 相同 `insert`) (中文(简体) ). |
| `GET /api/v1/pipelines/{id}/documents/{docId}` | 一份文件,或404. |
| `DELETE /api/v1/pipelines/{id}/documents/{docId}` | 204,或为不明文件的404. |

### 检索

1.  **作是语已.** `PUT /__admin/retrieval {match: {contains?, pipeline?}, nodes: [{text, score?, metadata?}]}` 增加一条规则。 最近增加的规则 `contains` 在查询中显示 (对案件不敏感) `pipeline` (身份或名称)匹配其 `nodes` 逐字记录, 被截至上克. 一个没有分数的节点得到1,0.9,0.8,. . `scripted_<n>`。 。 。 .
2.  **默认: 术语重叠 .** 术语是小写字母数字词 2+ 字符减 常见止语. 文档的分数是查询中在它的 文本或内容 `metadata.title`,四舍五入到4个位置。 不匹配的文件被丢弃并绑定 保持插入顺序。 每个文档都是一个节点(`id_: "<docId>_0"`)及其元数据收益 `document_id` 财务报告和审定财务报表 `pipeline_id`,后端读取的字段.

节点元数据在两者下发送 `metadata` (通过我们的后端阅读)和 `extra_info` (单位:千美元) 官方客户端模型的字段名). 没有身份证明, 谁是真正的API 发送是未经证实的.

### Python 聊天 SDK: 经核实的呼叫序列

目录中将此列为未核实. 现已与安装的SDK核对: 拉玛-云层服务 **0.6.88 (中文(简体) )**拉玛-云 **0.1.45 (中文(简体) )** 和马拉马指数核心 **0.14.10 (中文(简体) )**,则 版本消费者应用的Python聊天服务针. 车轮被读取 `llamacloud.sdk.test.ts` 运行服务的真实 `LlamaCloudClient` 在真实的 SDK 相对 模拟器. `LlamaCloudIndex(name, project_name=…, api_key=…)` 接下来是 `.as_retriever(similarity_top_k=5).aretrieve(q)` 发出这些呼吁:

1.  `GET /api/v1/projects?project_name=<name>`数字 : `resolve_project`。没有匹配加价 `No project found with name …`,并且不止一场比赛也提高了.
2.  `GET /api/v1/pipelines?project_id=<id>&pipeline_name=<index>&pipeline_type=MANAGED`数字 : `resolve_pipeline`。没有匹配加价 `Unknown index name …`。 。 。 .
3.  `GET /api/v1/pipelines/{id}`,则 `GET /api/v1/projects/{project_id}`数字 : `as_retriever()` 构建一个 `LlamaCloudRetriever(project_id=…, pipeline_id=…)`,它再次通过id解决了两者.
4.  `POST /api/v1/pipelines/{id}/retrieve {query, dense_similarity_top_k: 5}`。 。 。 .

基础 URL 来源 `base_url` 或者说 `LLAMA_CLOUD_BASE_URL`后退为 `https://api.cloud.llamaindex.ai` (单位:千美元)`llama_index.core.ingestion.api_utils.get_client`) (中文(简体) ). 这个 客户端没有通过 `base_url`,所以设置环境变量就够了。 SDK的烟花型号 严格: `Pipeline.status` 必须是 `CREATED` 或者说 `DELETING`,以及 `embedding_config` 实值 所需经费。 模拟器既能满足两者,而SDK测试如果形状漂移会失败.

**差异 :** python 客户端 `llamacloud_project_name` 默认为 `"default"` (小写. 这个 后端的默认值是 `"Default"`. 项目检查准确,所以需要 `LLAMACLOUD_PROJECT_NAME=Default`,或种子 `default` 项目。 否则,客户会退化 以空取结果表示,接受测试涵盖这些结果.

运行 SDK 测试 :

```bash
uv venv /tmp/llama && VIRTUAL_ENV=/tmp/llama uv pip install \
  llama-cloud-services==0.6.88 llama-cloud==0.1.45 llama-index-core==0.14.10
MOCKINGBIRD_LLAMACLOUD_PYTHON=/tmp/llama/bin/python \
  MOCKINGBIRD_LLAMACLOUD_PY_CLIENT=/path/to/llamacloud_client.py bun test llamacloud.sdk
```

### 管理员(超过标准合同)

| 路线 | 效果 |
| --- | --- |
| `GET /__admin/pipelines` | 命名空间的项目和管道. |
| `PUT /__admin/pipelines` | `{name, projectName?}` 建立管理下的管道,必要时建立其项目。 ids是来自取名空间和取名的稳定的UUID. |
| `GET /__admin/pipelines/:pipeline/documents` | 一个管道的文件, 通过身份或名称. |
| `GET /__admin/retrieval` | 剧本规则,最新第一. |
| `PUT /__admin/retrieval` | 添加一条规则, 或全部替换为 `{rules: [...]}` (列出的第一个胜出). |
| `DELETE /__admin/retrieval` | 清规取道. |
| `GET/PUT /__admin/settings` | `{apiKeys?: string[], defaultTopK?: number}` 呼叫的命名空间. |

错误预设( E)`POST /__admin/faults {"preset": "<name>", "count"?: n}`· ; `GET /__admin/faults/presets`:

| 预设 | 效果 |
| --- | --- |
| `index_missing` | 管道搜索答案 `[]`。 。 。 . |
| `retrieval_empty` | 检索解答节点. |
| `documents_unexpected_shape` | 文档列表回答对象而不是数组. |
| `unauthorized` | 每个呼叫都答401. |
| `rate_limited` | 每通通电话答429. |
| `server_error` | 每召答五百个. |
| `slow_retrieval` | 检索延迟 3 s, 或 `latencyMs` 当给予. |

### 命名空间

消费者都无法添加信头,因此可以选择三个方式:

-   页:1 `x-mockingbird-namespace` 页眉;
-   (单位:千美元) `/__admin/ns/<name>` 基准 URL 前缀;
-   aPI 密钥 : `PUT /__admin/credentials {"credentials": {"<LLAMACLOUD_API_KEY>": "<namespace>"}}`。 。 。 .

每个命名空间从种子管道开始,默认情况下 `acme-member-kb-v1` 在项目中 `Default`。请求的日记记录了操作编号、状态和管道及文件编号。 这个 从不记录查询、文档文本或标题.

### 故意不模拟

-   真实的检索质量:没有嵌入,分块,混合搜索,重新排序,元数据过滤器, 图像或页面图节点,或 `retrieval_mode` 出行路线. 文件总是一个节点.
-   管道摄入状态和同步任务. 可立即取回上层文档.
-   文件上传( E)`/api/v1/files`, (中文(简体) ), `pipeline_files`),数据源,解析(LlamaParse)和 提取.
-   通过API创建项目或管道. 使用种子或 `PUT /__admin/pipelines`。 。 。 .
-   每个命名空间一个以上的组织.

## API 密码

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `LlamaCloudAPI` | 类 | 进程模拟器 : `fetch(request)`, (中文(简体) ), `reset()`, (中文(简体) ), `documents(pipeline)`, (中文(简体) ), `addRule(rule)`, (中文(简体) ), `rules()`, (中文(简体) ), `clearRules()`, (中文(简体) ), `state`选项: `sqlite`, (中文(简体) ), `now`, (中文(简体) ), `namespace`, (中文(简体) ), `pipelines`, (中文(简体) ), `settings`。 。 。 . |
| `createRuntime` | 函数 | 全面服务合同的仿真器(保健、管理员、命名空间、证书、预设)。 选项 : `pipelines`, (中文(简体) ), `settings`, (中文(简体) ), `clock`, (中文(简体) ), `seed`, (中文(简体) ), `adminKey`, (中文(简体) ), `onLog`, (中文(简体) ), `sqlite`。 。 。 . |
| `LLAMACLOUD_PRESETS` | 对象 | 每个命名的断层预设. |
| `LLAMACLOUD_NAMESPACE` | 字符串 | 服务名称, `"llamacloud"`。 。 。 . |
| `DEFAULT_PIPELINES`, (中文(简体) ), `DEFAULT_PIPELINE_NAME`, (中文(简体) ), `DEFAULT_PROJECT_NAME`, (中文(简体) ), `DEFAULT_SETTINGS` | 数值 | 种子: `acme-member-kb-v1` 内 `Default`\-k5,任何钥匙. |
| `rank`, (中文(简体) ), `terms` | 函数 | 默认的名词重叠排名及其标注符. |
| `uuidFrom` | 函数 | 用于项目、管道和文件编号的稳定UUID衍生物. |
| `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds` | 数值 | 销售商为OpenAPI合同及其业务代号. |
| `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` (单位:千美元)`./server`(中文(简体) ) | 节点 | 服务过来 `node:http`; 数据 `serve` CLI目标(`--index`, (中文(简体) ), `--project`, (中文(简体) ), `--api-key`; 第8805号口. |

部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

## 常见问题

### @crvouga/mockingbird-service-llamacloud 是什么？

LlamaCloud平台 API 的状态仿真器:项目和管线检查,管线文件,以及确定性\(标注或期限重叠\)取回,对照官方 lama cloud services SDK进行校验\.

### 如何安装 @crvouga/mockingbird-service-llamacloud？

在项目目录运行 npm install @crvouga/mockingbird-service-llamacloud，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-llamacloud，可以用 npx mockingbird-llamacloud 直接运行。

### @crvouga/mockingbird-service-llamacloud 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crvouga/mockingbird-service-llamacloud 支持 ESM 还是 CommonJS？

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

### @crvouga/mockingbird-service-llamacloud 可以商用吗？

@crvouga/mockingbird-service-llamacloud 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crvouga/mockingbird-service-llamacloud 的下载量有多少？

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

### @crvouga/mockingbird-service-llamacloud 还在维护吗？

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