> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Node.js SDK 运行

> 使用 @fetch-hive/sdk 包从 Node.js 或 TypeScript 调用提示词部署

# 使用 Node.js SDK 运行

当你想从 Node.js 或 TypeScript 调用提示词部署时，请使用官方的 `@fetch-hive/sdk` 包。SDK 用类型化的客户端包装了公共的 [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) 端点，处理身份验证，并将流式响应作为 `AsyncIterable` 公开。

## 安装

```bash theme={null}
npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
```

该 SDK 针对 Node.js 18+（使用全局 `fetch`），并开箱即用地附带 TypeScript 类型定义。

## 身份验证

将 `FETCH_HIVE_API_KEY` 环境变量设置为你的工作区 API 密钥：

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();
```

或显式传入密钥：

```typescript theme={null}
const client = new FetchHive({ apiKey: 'fhk_...' });
```

有关如何创建和轮换密钥，请参阅 [API 密钥](https://docs.fetchhive.com/zh/workspace/api-keys.md)。

## 基本示例

调用提示词部署并读取最终响应：

```typescript theme={null}
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();

const result = await client.invokePrompt({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { text: 'Fetch Hive helps teams ship AI products faster.' },
});

console.log(result.response);
```

`invokePrompt` 返回一个 `Promise`，在提示词完成后解析为已解析的 JSON 主体。请参阅 [非流式响应结构](https://docs.fetchhive.com/zh/api-reference/prompts/invoke.md#response)。

## 方法参考

| 字段 | 类型 | 必填 | 描述 |
| - | - | - | - |
| `deployment` | `string` | 是 | 提示词部署名称 |
| `variant` | `string` | 否 | 部署变体名称 |
| `inputs` | `Record<string, unknown>` | 否 | 提示词变量的键值对 |
| `user` | `string` | 否 | 在 [用户跟踪](https://docs.fetchhive.com/zh/user-tracking/overview.md) 中显示的不透明调用方标识符 |
| `metadata` | `Record<string, string \| number \| boolean \| null>` | 否 | 调用方定义的扁平元数据，用于审计和日志过滤。请参阅 [调用元数据](https://docs.fetchhive.com/zh/user-tracking/invoke-metadata.md) |

SDK 会为 `invokePrompt` 注入 `streaming: false`。要使用流式，请使用下面的 `invokePromptStream`。

## 处理响应

```typescript theme={null}
const result = await client.invokePrompt({
  deployment: 'my-prompt',
  variant: 'default',
});

console.log(result.response);     // final text
console.log(result.model);        // model identifier
console.log(result.usage);        // token usage breakdown
console.log(result.request_id);   // use this to look up the run in Logs
```

## 流式响应

使用 `invokePromptStream` 在到达时接收 Server-Sent Events。该方法返回一个可使用 `for await` 消费的 `AsyncIterable`：

```typescript theme={null}
for await (const chunk of client.invokePromptStream({
  deployment: 'YOUR_DEPLOYMENT_NAME',
  variant: 'YOUR_VARIANT_NAME',
  inputs: { text: 'Fetch Hive helps teams ship AI products faster.' },
})) {
  if (chunk.type === 'response') {
    process.stdout.write(chunk.response ?? '');
  } else if (chunk.type === 'usage') {
    console.log('\n\nUsage:', chunk.usage);
  }
}
```

该流会产生 [调用提示词 → 响应](https://docs.fetchhive.com/zh/api-reference/prompts/invoke.md#response) 中记录的相同事件类型：`reasoning`、`response`、最终的 `usage` 事件，或在提供商在流中失败时产生的 `error` 事件。

## 配置

| 选项 | 默认值 | 描述 |
| - | - | - |
| `apiKey` | `process.env.FETCH_HIVE_API_KEY` | 来自仪表板的 Bearer 令牌 |
| `baseURL` | `https://api.fetchhive.com/v1` | 覆盖 API 基础 URL |

```typescript theme={null}
const client = new FetchHive({
  apiKey: 'fhk_...',
  baseURL: 'https://api.fetchhive.com/v1',
});
```

## 错误

非 2xx 响应会抛出一个 `Error`，其消息包含状态码和响应体：

```typescript theme={null}
try {
  const result = await client.invokePrompt({
    deployment: 'my-prompt',
    variant: 'default',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
```

有关状态码含义，请参阅 [错误与速率限制](https://docs.fetchhive.com/zh/api-reference/errors-and-rate-limits.md)。

## 链接

* [npm 上的软件包](https://www.npmjs.com/package/@fetch-hive/sdk)
* [GitHub 上的源码](https://github.com/Fetch-Hive/nodejs-sdk)

## 后续步骤

* [使用 API 运行](https://docs.fetchhive.com/zh/prompts/run-with-api.md) - 使用 cURL 的相同流程
* [使用 Python SDK 运行](https://docs.fetchhive.com/zh/prompts/run-with-python-sdk.md)
* [使用 Ruby SDK 运行](https://docs.fetchhive.com/zh/prompts/run-with-ruby-sdk.md)
* [使用 PHP SDK 运行](https://docs.fetchhive.com/zh/prompts/run-with-php-sdk.md)
* [调用提示词](https://docs.fetchhive.com/zh/api-reference/prompts/invoke.md) - 完整端点参考


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.