对流-外形

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

快速启动

1. 安装组件

npm install @exalabs/convex-exa zod

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

2. 配置对流

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

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. 设置环境变量

将此添加到您的 凸起板 环境变量:

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

4. 使用该构成部分

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 上突出显示或文本时.

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" 默认。 需要结构化或合成输出时使用 .

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。 。 。 .

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

参数:

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

所需资源

• 欧克萨 账户和 API 密钥
• 1.39.1或以后的对流
• zod 当使用图案时 deepSearch

如何运作

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

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

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

发展

建设构成部分

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

# 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) (中文(简体) ).

示例应用

对抗现场部署

npm run dev

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

见 实例/README.md 说明:

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

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

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

见 exa API 文档 关于现有参数和能力的充分参考.