TypeScript SDK - Conare

conare 为 Node 18 及以上版本和 Bun 封装了 API，没有任何依赖。

npm install conare

import { Conare } from "conare";

const conare = new Conare(); // reads CONARE_API_KEY
const docs = conare.namespace("docs");

await docs.add({ text: "Refunds are available for 30 days." });
const results = await docs.query("how do refunds work?");

Result

[
  {
    "id": "doc_HmsFWqbQQc2mY03FhVZE",
    "text": "Refunds are available for 30 days.",
    "score": 0.3192,
    "reranked": true,
    "metadata": {}
  }
]

响应字段采用 camelCase，时间戳为 Date。

选项

new Conare({
  apiKey: "sk-conare-...",           // default: CONARE_API_KEY
  baseURL: "https://api.conare.ai",  // default: CONARE_BASE_URL
  timeout: 60_000,                   // ms per attempt
  maxRetries: 2,
  organization: "org_...",           // for a multi-organization key
});

每个方法的最后一个参数还可传入 { signal, timeout, idempotencyKey }。

方法

方法	返回值
`conare.namespace(name)`	命名空间句柄；调用方法前不会发送任何请求
`conare.namespaces({ prefix })`	`[{ name, documents, embeddingModel, rerankModel }]`
`ns.add(docs)`	id 列表
`ns.write(docs)`	`[{ id, version, result, chunks, chunksEmbedded }]`
`ns.query(query, { topK, filter, rerank, rerankDepth, retrievers, user, userPrefix, excludeIds, hops })`	`[{ id, text, score, reranked, metadata }]`
`ns.queryPages(query, { maxResults, ... })`	分页的异步迭代器
`ns.get(id)`	文档，或 `null`
`ns.list({ limit })`	遍历所有文档的异步迭代器
`ns.delete(id)`	无
`ns.deleteMany(ids)`, `ns.deleteWhere(filter)`	删除的数量
`ns.create({ embeddingModel })`	`{ embeddingModel }`
`ns.drop({ force })`	`{ sourcesDeleted }`
`ns.uploadFile(file, name, { id, type, user, metadata, pages, password, layout, wait })`	上传记录，以及 `ready` 后的 Markdown
`ns.getFile(fileId, { user })`	该文件最新的上传记录
`conare.parse(file or { url }, { name, type, pages, password, layout, wait })`	文件的 Markdown，不存储任何内容
`conare.getParse(id)`	返回 `parsing` 的解析任务
`conare.embed(texts, { type, outputDtype })`	向量；使用 `int8` 时为 `{ values, scales }`（`dequantize` 可将其还原）
`conare.rerank(query, documents, { topK })`	`[{ index, score, document }]`，附带 `unscored`
`conare.sources`	`connect`、`create`、`list`、`get`、`sync`、`update`、`delete`、`types`
`conare.organizations()`	该密钥代表的组织
`conare.users.delete(user)`, `deletePrefix(prefix)`	删除用户数据的任务
`conare.events.list({ cursor, types })`	按顺序列出的变更

add 和 write 接受单个文档或任意大小的数组，每次发送 100 个。
搜索所有命名空间（POST /query）和 answer 暂无对应方法：请通过 HTTP 调用。

错误

所有失败都会抛出 ConareError，包含 status、code、message 和 requestId。

import { ConareError } from "conare";

try {
  await docs.add({ text: "" });
} catch (err) {
  if (err instanceof ConareError) console.log(err.status, err.code); // 400 "invalid_request"
}

情况	行为
无响应	`status` 为 `0`，`code` 为 `timeout` 或 `connection_error`
`429`、`5xx`、网络错误	在 `Retry-After` 或退避之后重试，最多 `maxRetries` 次
写入	携带 `Idempotency-Key`，因此重试绝不会重复写入