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

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# 嵌入与重排序

> 通过兼容 OpenAI 和 Cohere 的端点，将 Conare 的嵌入和重排序模型与任意向量数据库搭配使用。

将您的 OpenAI 或 Cohere 客户端指向 `https://api.conare.ai/v1`，即可单独使用 Conare 的模型。**Models only** [密钥](https://docs.conare.ai/zh/console.md#密钥)可以调用这些模型，但无法访问任何命名空间。

| 模型 | 用途 | 输出 |
| - | - | - |
| `conare-embed-1` | 文档和查询的嵌入 | 1,024 维 |
| `conare-rerank-1` | 重排序（默认） | 每个文档一个相关性分数 |

## 嵌入

`POST /v1/embeddings`

文档直接嵌入，搜索查询则使用 `input_type: "query"`。

```bash curl theme={null}
curl https://api.conare.ai/v1/embeddings \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "conare-embed-1", "input": ["Refunds are available for 30 days."]}'

curl https://api.conare.ai/v1/embeddings \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "conare-embed-1", "input": "how do refunds work?", "input_type": "query"}'
```

```ts TypeScript theme={null}
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.conare.ai/v1", apiKey: process.env.CONARE_API_KEY });

const docs = await client.embeddings.create({ model: "conare-embed-1", input: ["Refunds are available for 30 days."] });
const query = await client.embeddings.create({
  model: "conare-embed-1",
  input: "how do refunds work?",
  input_type: "query",
} as OpenAI.EmbeddingCreateParams);
```

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.conare.ai/v1", api_key=os.environ["CONARE_API_KEY"])

docs = client.embeddings.create(model="conare-embed-1", input=["Refunds are available for 30 days."])
query = client.embeddings.create(
    model="conare-embed-1",
    input="how do refunds work?",
    extra_body={"input_type": "query"},
)
```

```json Response theme={null}
{
  "data": [{ "embedding": [0.12506497, 0.07159516, 0.017521178, ...], "index": 0, "object": "embedding" }],
  "model": "conare-embed-1",
  "object": "list",
  "usage": { "prompt_tokens": 12, "total_tokens": 12 }
}
```

| 选项 | 类型 | 作用 |
| - | - | - |
| `input` | string 或 array，必填 | 1-128 段文本，每段最大 32 KiB |
| `model` | string | `conare-embed-1`（默认），或您自己模型的 id |
| `input_type` | string，默认 `document` | 搜索查询使用 `query` |
| `encoding_format` | string，默认 `float` | `float`，或 `base64` 表示小端序 float32 |
| `dimensions` | integer | 仅支持模型自身的 1,024 |

`data` 中每个输入对应一个包含 1,024 个数值的 `embedding`，并附带其 `index`。完整 schema：[嵌入文本（兼容 OpenAI）](https://docs.conare.ai/zh/api-reference/models/embed-texts-openai-compatible.md)。

## 重排序

`POST /v1/rerank`

按查询为文档打分，最佳结果排在最前；它接受 Cohere 的请求格式，`/v2/rerank` 则接受 Cohere 的 `ClientV2`。

```bash curl theme={null}
curl https://api.conare.ai/v1/rerank \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how do refunds work?",
    "documents": ["Orders ship within two days.", "Refunds are available for 30 days."],
    "top_n": 1
  }'
```

```ts TypeScript (SDK) theme={null}
import { Conare } from "conare";

const conare = new Conare();
const ranked = await conare.rerank("how do refunds work?", [
  "Orders ship within two days.",
  "Refunds are available for 30 days.",
]);
// [{ index: 1, score: 0.3468, document: "Refunds are available for 30 days." }, ...]
```

```python Python theme={null}
import os
import cohere

co = cohere.Client(base_url="https://api.conare.ai", api_key=os.environ["CONARE_API_KEY"])

response = co.rerank(
    query="how do refunds work?",
    documents=["Orders ship within two days.", "Refunds are available for 30 days."],
    top_n=1,
)
```

```json Response theme={null}
{
  "id": "d9d8ac5739d77af256c01449d7f23bb2",
  "model": "conare-rerank-1",
  "results": [{ "index": 1, "relevance_score": 0.3484 }],
  "unscored": [],
  "usage": { "total_tokens": 57 }
}
```

| 选项 | 类型 | 作用 |
| - | - | - |
| `query` | string，必填 | 最多 8,192 个字符 |
| `documents` | array，必填 | 1-100 个字符串，或带 `text` 的对象；使用为您训练的模型时最多 1,000 个 |
| `model` | string | 省略即使用 `conare-rerank-1`；未知模型返回 `400` |
| `top_n` | integer | 仅返回最佳的 `top_n` 个 |
| `return_documents` | boolean，默认 `false` | 以 `document` 包含每个文档的文本 |
| `max_tokens_per_doc` | integer | 将每个文档截断到大约这么多 token |

| 字段 | 含义 |
| - | - |
| `results` | 最佳结果在前：`documents` 中的 `index`，以及 `relevance_score`（越高越好） |
| `unscored` | 重排序器未能及时处理的文档 |
| `id`、`usage` | 请求 id，以及读取的 token 数 |

完整 schema：[重排序（兼容 Cohere）](https://docs.conare.ai/zh/api-reference/models/rerank-documents-cohere-and-vllm-compatible.md)、[重排序（Cohere v2）](https://docs.conare.ai/zh/api-reference/models/rerank-documents-cohere-v2-compatible.md)。

## 模型

`GET /v1/models`

在 `data` 中列出您的密钥可以调用的模型，包括为您的组织训练的模型。

* 每个模型都有 `id` 和 `type`（`embedding` 或 `rerank`）；即将停用的模型带有 `sunset` 日期和 `successor`。
* `GET /v1/models/:id` 返回单个模型，或返回 `404 model_not_found`。

完整 schema：[列出模型](https://docs.conare.ai/zh/api-reference/models/list-models-openai-compatible.md)。

## 原生路由

Conare 自有的格式，[SDK](https://docs.conare.ai/zh/sdk.md) 使用此格式。

`POST /embed`

```ts TypeScript theme={null}
const [vector] = await conare.embed("how do refunds work?", { type: "query" });
const int8 = await conare.embed("how do refunds work?", { type: "query", outputDtype: "int8" });
```

```json Response theme={null}
{ "dimensions": 1024, "embeddings": [[0.15636191, 0.03499228, -0.003388892, ...]], "model": "conare-embed-1" }
```

| 选项 | 类型 | 作用 |
| - | - | - |
| `input` | array，必填 | 1-128 段文本 |
| `type` | string，默认 `document` | 搜索查询使用 `query` |
| `output_dtype` | string，默认 `float` | `int8` 返回 -127 到 127 的整数，并在 `scales` 中为每个向量返回一个缩放因子；余弦相似度不变 |

完整 schema：[嵌入文本](https://docs.conare.ai/zh/api-reference/models/embed-texts.md)。

`POST /rerank`

```json Response theme={null}
{
  "model": "conare-rerank-1",
  "results": [{ "index": 1, "score": 0.3484 }, { "index": 0, "score": 0.1169 }],
  "unscored": []
}
```

| 选项 | 类型 | 作用 |
| - | - | - |
| `query` | string，必填 | 最多 8,192 个字符 |
| `documents` | array，必填 | 1-100 个字符串，使用为您训练的模型时最多 1,000 个 |
| `top_k` | integer | 仅返回最佳的 `top_k` 个 |

完整 schema：[重排序文档](https://docs.conare.ai/zh/api-reference/models/rerank-documents.md)。


## Related topics

- [简介](https://docs.conare.ai/zh/index.md)
- [API 概览](https://docs.conare.ai/zh/api.md)
- [搜索](https://docs.conare.ai/zh/query.md)
- [控制台](https://docs.conare.ai/zh/console.md)
- [MCP](https://docs.conare.ai/zh/mcp-server.md)


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