# @codefionn/llmleaf-client 中文文档

规范地址：https://npmcn.com/package/%40codefionn/llmleaf-client/

版本：0\.6\.4
npm 元数据更新时间：2026-10-11T11:23:33.745Z
中文译文更新时间：2026-11-10T06:37:07.214Z
软件包许可：MIT OR Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40codefionn/llmleaf-client
原文对照：https://npmcn.com/package/%40codefionn/llmleaf-client/?lang=original
项目主页：https://github.com/codefionn/llmleaf/tree/main/clients/typescript
源码仓库：https://github.com/codefionn/llmleaf

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

- 包体积（解压后）：550 kB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-06-22T05:00:09.084Z
- 最新版本发布：2026-10-11T11:23:33.467Z
- 近 30 天下载量：5450（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

官方TypeScript/JavaScript客户端为llmleaf LLM代理.

## 安装

```sh
npm install @codefionn/llmleaf-client
```

也可以使用：`pnpm add @codefionn/llmleaf-client`、`yarn add @codefionn/llmleaf-client`、`bun add @codefionn/llmleaf-client`

## README

# @codefionn/llmleaf-客户端

TypeScript / JavaScript 客户端 [叶子](https://npmcn.com/package/) LLM 代理服务器.

在 HTTP 上说 llmleaf 的 OpenAI/ OpenRouter 形状的 JSON(参见 [`../SPEC.md`](https://npmcn.com/package/%40codefionn/SPEC.md)) (中文(简体) ). 零运行时间依赖度超过 `@bufbuild/protobuf` 运行时间,它运行 任何地方 全球 `fetch` 编号 : `ReadableStream` 编号 : `FormData` 存在 – 节点20+, Deno, Bun, 浏览器.

## 安装

```sh
npm install @codefionn/llmleaf-client
```

## 示例

```ts
import { LlmleafClient, Role } from "@codefionn/llmleaf-client";

const client = new LlmleafClient({
  baseUrl: "https://gateway.example.com",
  apiKey: process.env.LLMLEAF_API_KEY!,
  timeoutMs: 30_000,   // optional; 0/omitted = no timeout. Also: adminToken, fetch
});

// Non-streaming chat
const res = await client.chat({
  model: "gpt-4o-mini",
  messages: [{ role: Role.USER, content: "Say hi." }],
});
console.log(res.choices[0]?.message.content);

// Streaming chat — async iterable of chunks, stops at `data: [DONE]`
for await (const chunk of client.chatStream({
  model: "gpt-4o-mini",
  messages: [{ role: Role.USER, content: "Count to 5." }],
})) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? "");
}

// Responses dialect (POST /v1/responses) — `input` is a bare string or an item array
const resp = await client.responses({
  model: "gpt-4o-mini",
  input: [{ type: "message", role: "user", content: "Say hi." }],
});

// Streaming responses — typed events, NO `[DONE]`; stops on the terminal
// response.completed / .incomplete / .failed event; unknown event types are skipped
for await (const event of client.responsesStream({
  model: "gpt-4o-mini",
  input: "Count to 5.",
})) {
  if (event.type === "response.output_text.delta") process.stdout.write(event.delta ?? "");
}
```

流媒体工具调用被曝光为 `choice.delta.toolCalls`按选择索引排列的组块 和每个 `ToolCallDelta.index`; 保留 `id` 编号 : `type` / 函数 `name` 随时随地,并附上 `function.arguments` 片段按到达顺序排列,直到 `finishReason === FinishReason.TOOL_CALLS`。 。 。 .

## 终点

```ts
await client.chat(req);              // POST /v1/chat/completions
client.chatStream(req);              // stream:true, async iterable of chunks
await client.responses(req);         // POST /v1/responses (OpenAI Responses dialect)
client.responsesStream(req);         // stream:true, async iterable of typed events (no [DONE])
await client.embeddings(req);        // base64 vectors decoded to floats
await client.rerank(req);            // POST /v1/rerank; results by relevance (plain JSON)
await client.decisions(req);          // POST /v1/decisions; structured decision answers
await client.listModels({ type: "llm" });
await client.speech(req);            // -> { bytes, contentType }
await client.voices("tts-1");
await client.transcribe(file, req);  // multipart; json/verbose_json -> object, text/srt/vtt -> tr.text
await client.createBatch(req);
await client.getBatch(id);
await client.cancelBatch(id);
client.batchResults(id);             // async iterable of result lines
```

自由形式字段( E)`extra`, (中文(简体) ), `responseFormat.jsonSchema`, (中文(简体) ), `functionDef.parameters`,)为生 JSON 字符串——通过 `JSON.stringify(obj)` 和相接相接的运算值; `extra` 键在请求的顶端合并.

## 决定

```ts
const decision = await client.decisions({
  model: "jev",
  state: { turn: 2 },
  questions: {
    route: { type: "choice", instructions: "Which route?", criteria: { left: null, right: null } },
  },
});
console.log(decision.answers.route);
```

`state`, (中文(简体) ), `questions`,答案,和决定元数据使用本地JSON值. `extra` 是一个 结构化对象合并到正文; 无法覆盖 `model`, (中文(简体) ), `state`,或 `questions`。 。 。 .

## 错误

任何非-2xx 响应都会丢出一个键入 `ApiError`数字 :

```ts
import { ApiError } from "@codefionn/llmleaf-client";

try {
  await client.chat(req);
} catch (e) {
  if (e instanceof ApiError) console.error(e.status, e.message); // 403 "model not allowed"
}
```

## 运行示例

[`examples/basic.ts`](https://npmcn.com/package/%40codefionn/llmleaf-client/examples/basic.ts) 进行聊天、流线和模型列表:

```sh
LLMLEAF_BASE_URL=https://gateway.example.com LLMLEAF_API_KEY=sk-… npx tsx examples/basic.ts
```

## 从原生再生

生成的文件( E)`src/gen/llmleaf/v1/llmleaf_pb.ts`)是犯法的 原型变化 :

```sh
npm install      # fetch the @bufbuild/protoc-gen-es plugin
npm run gen      # runs scripts/gen.sh (needs protoc on PATH)
```

## 页:1

-   线上绘图是手写(`src/wire.ts`因为Protobuf -es的JSON密码发出 骆驼Case + `SCREAMING_CASE`,这不是 OpenAI 线条(snake case + 小写符号). 生成的描述符在 `gen` 导出用于反射 .
-   解码器是宽大处理的(允许出/出田)。 不得复试. `chatStream` 编号 : `batchResults` 需要一个能流的 `fetch`。实时 WebSocket 已超出范围.

## 常见问题

### @codefionn/llmleaf-client 是什么？

官方TypeScript/JavaScript客户端为llmleaf LLM代理\.

### 如何安装 @codefionn/llmleaf-client？

在项目目录运行 npm install @codefionn/llmleaf-client，或使用 pnpm add / yarn add / bun add。

### @codefionn/llmleaf-client 支持 TypeScript 吗？

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

### @codefionn/llmleaf-client 支持 ESM 还是 CommonJS？

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

### @codefionn/llmleaf-client 需要什么版本的 Node\.js？

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

### @codefionn/llmleaf-client 可以商用吗？

@codefionn/llmleaf-client 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @codefionn/llmleaf-client 的下载量有多少？

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

### @codefionn/llmleaf-client 还在维护吗？

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