# @exalabs/convex-exa 中文文档

规范地址：https://npmcn.com/package/%40exalabs/convex-exa/

版本：0\.1\.1
npm 元数据更新时间：2026-08-04T15:01:41.349Z
中文译文更新时间：2026-11-14T03:04:47.188Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40exalabs/convex-exa
原文对照：https://npmcn.com/package/%40exalabs/convex-exa/?lang=original
项目主页：https://github.com/exa-labs/exa-convex#readme
源码仓库：https://github.com/exa-labs/exa-convex

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

- 包体积（解压后）：76.6 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：convex ^1\.39\.1，zod ^3\.24\.0
- 首次发布：2026-06-03T15:49:30.389Z
- 最新版本发布：2026-08-04T15:01:40.929Z
- 近 30 天下载量：4955（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

用 Exa 进行网络搜索和内容提取的对流组件

## 安装

```sh
npm install @exalabs/convex-exa
```

也可以使用：`pnpm add @exalabs/convex-exa`、`yarn add @exalabs/convex-exa`、`bun add @exalabs/convex-exa`

## README

# 对流-外形

Convex应用程序的网络搜索和内容提取. 搜索网页,拉出干净的页面内容,并返回结构化的答案.

## 快速启动

### 1\. 安装组件

```bash
npm install @exalabs/convex-exa zod
```

`zod` 需要当您通过 Zod 时 `schema` 改为 `deepSearch`。 。 。 .

### 2\. 配置对流

将组件添加到您的 `convex/convex.config.ts`数字 :

```typescript
import { defineApp } from "convex/server";
import { v } from "convex/values";
import exa from "@exalabs/convex-exa/convex.config";

const app = defineApp({
  env: {
    EXA_API_KEY: v.string(),
  },
});

app.use(exa, {
  name: "exa",
  env: {
    EXA_API_KEY: app.env.EXA_API_KEY,
  },
});

export default app;
```

### 3\. 设置环境变量

将此添加到您的 [凸起板](https://dashboard.convex.dev/) 环境变量:

| 变量 | 说明 |
| --- | --- |
| `EXA_API_KEY` |  [欧克萨](https://dashboard.exa.ai/) API 密钥 |

也可以从CLI中设定: `npx convex env set EXA_API_KEY <your-key>`。 。 。 .

### 4\. 使用该构成部分

```typescript
import { action } from "./_generated/server";
import { ExaClient } from "@exalabs/convex-exa";
import { components } from "./_generated/api";
import { z } from "zod";

const exa = new ExaClient(components.exa);

export const searchNews = action({
  handler: async (ctx) => {
    return await exa.search(ctx, {
      query: "recent llm launches",
      contents: {
        highlights: true,
        maxAgeHours: 24,
      },
    });
  },
});

export const summarizeFunding = action({
  handler: async (ctx) => {
    return await exa.deepSearch(ctx, {
      query: "recent AI startup funding announcements",
      systemPrompt: "Prefer official sources and avoid duplicate reporting.",
      schema: z.object({
        summary: z.string(),
        companies: z.array(z.string()),
      }),
    });
  },
});

export const fetchKnownPage = action({
  handler: async (ctx) => {
    return await exa.contents(ctx, {
      urls: ["https://exa.ai/docs"],
      highlights: true,
      maxAgeHours: 12,
    });
  },
});
```

## API 参考

### `search(ctx, args)`

运行 Exa `/search` 与 `type: "auto"` 默认。 用于一般检索; 通过嵌入 `contents` 当您想要在结果 URL 上突出显示或文本时.

```typescript
await exa.search(ctx, {
  query: "battery recycling policy changes in the EU",
  contents: {
    highlights: true,
  },
});
```

**参数:**

-   `query` - 搜索查询
-   `contents` - 文本、亮点、摘要、, `maxAgeHours`等 (中文(简体) ).
-   其他字段则转发给 Exa 搜索 API( filters, ), `numResults`, (中文(简体) ), `type`页:1

* * *

### `deepSearch(ctx, args)`

运行 Exa `/search` 与 `type: "deep"` 默认。 需要结构化或合成输出时使用 .

```typescript
await exa.deepSearch(ctx, {
  query: "Compare recent frontier model launches",
  schema: z.object({
    summary: z.string(),
    models: z.array(z.string()),
  }),
});
```

**参数:**

-   `query` - 搜索查询
-   `schema` - 结构输出的Zod schema(转换为JSON Schema for Exa)
-   `outputSchema` - Raw JSON Schema 而不是Zod) - 对 - Raw JSON Schema 而不是Zod
-   `systemPrompt` - 深度搜索模式的任择指导
-   `type` - 一个 `deep-lite`, (中文(简体) ), `deep`, (中文(简体) ), `deep-reasoning`

**回返情况:** Exa 搜索响应; 提供时结构化字段遵循您的计划

* * *

### `contents(ctx, args)`

通过 Exa 获取您已经知道的 URL 的内容 `/contents`。 。 。 .

```typescript
await exa.contents(ctx, {
  urls: ["https://exa.ai/docs"],
  highlights: true,
  maxAgeHours: 12,
});
```

**参数:**

-   `urls` - 要获取的 URL
-   `text`, (中文(简体) ), `highlights`, (中文(简体) ), `summary` - 顶级内容选项(不嵌入) `contents` 喜欢上 `/search`(中文(简体) )

* * *

## 所需资源

-   [欧克萨](https://exa.ai/) 账户和 API 密钥
-   1.39.1或以后的对流
-   `zod` 当使用图案时 `deepSearch`

## 如何运作

此组件将 Exa API 包裹在一个 Convex 组件内. 您的行动呼吁 `ExaClient`,操作组件操作:

1.  读取 `EXA_API_KEY` 从组件环境配置
2.  调用 Exa `/search` 或者说 `/contents` 和你的争论
3.  返回输入结果到您的 Convex 动作

API 密钥会留在 Convex env 中—— 而不是客户端可见代码中 .

## 发展

### 建设构成部分

为在当地建立这一构成部分:

```bash
# Install dependencies
npm install
cd example && npm install && cd ..

# Build with Convex codegen (generates component API)
npm run build:codegen

# Or just build TypeScript
npm run build:esm

# Run tests
npm test
```

该构成部分需要部署Convex,以产生适当的构成部分API类型(`_generated/component.ts`) (中文(简体) ).

### 示例应用

对抗现场部署

```bash
npm run dev
```

这将运行实例 Convex 后端, 当 `src/` 变化.

见 [实例/README.md](https://npmcn.com/example/README.md) 说明:

-   `searchNews`:根据查询获取一般网络结果.
-   `deepResearch`:进行有条理和有计划驱动的深度搜索.
-   `fetchKnownPage`: 从一个特定的,已知的URL中提取内容.

这些实例动作突出显示您在自己的应用程序中可能想要调整的关键参数,例如:

-   按域过滤
-   通过文本过滤器包含或排除文本
-   设定返回的结果数量
-   选择搜索模式
-   选择内容模式( E)`highlights`, (中文(简体) ), `text`,或 `summary`(中文(简体) )
-   限制文档的调整 `maxAgeHours`

见 [exa API 文档](https://docs.exa.ai/) 关于现有参数和能力的充分参考.

## 常见问题

### @exalabs/convex-exa 是什么？

用 Exa 进行网络搜索和内容提取的对流组件

### 如何安装 @exalabs/convex-exa？

在项目目录运行 npm install @exalabs/convex-exa，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：convex（^1\.39\.1）、zod（^3\.24\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @exalabs/convex-exa 支持 TypeScript 吗？

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

### @exalabs/convex-exa 支持 ESM 还是 CommonJS？

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

### @exalabs/convex-exa 可以商用吗？

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

### @exalabs/convex-exa 的下载量有多少？

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

### @exalabs/convex-exa 还在维护吗？

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