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

# Rerank

<Note>
  Note: For setting the embedding model name, refer to the [System Supported Rerank Models List](https://geekai.dev/models). When switching models, you only need to modify the corresponding model name.
  The response data format is fully compatible with OpenAI.
</Note>

### cURL Request Example

```bash theme={null}
curl --location 'https://geekai.dev/api/v1/rerank' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_GEEKAI_API_KEY}' \
--data '{
    "model": "rerank-multilingual-v3.0",
    "query": "Where is the capital of the United States?",
    "top_n": 3,
    "documents": [
        "Carson City is the capital of the U.S. state of Nevada.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands located in the Pacific Ocean, and its capital is Saipan.",
        "Washington, D.C. (also known simply as Washington or D.C., and officially as the District of Columbia) is the capital of the United States, and it is a federal district.",
        "In English grammar, capitalization is the rule of using a capital letter at the beginning of a word, and the use of English differs from the capitalization rules of other languages.",
        "The existence of the death penalty in the United States dates back to before the United States became a country, and as of 2017, the death penalty is legal in 30 of the 50 states."
    ]
}
```


## OpenAPI

````yaml openapi.yaml POST /rerank
openapi: 3.1.0
info:
  title: 极客智坊 API文档
  description: 极客智坊 API 消息接口规范文档
  version: 1.0.0
servers:
  - url: https://geekai.co/api/v1
    description: 国内代理入口
  - url: https://geekai.dev/api/v1
    description: 海外代理入口
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /rerank:
    post:
      tags:
        - Rerank
      summary: 文本重排序接口
      description: 根据查询对文档列表进行相关性排序，适用于搜索结果优化、问答系统等场景。
      operationId: rerankDocuments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - query
                - documents
              properties:
                model:
                  type: string
                  description: 重排模型
                  example: rerank-multilingual-v3.0
                query:
                  type: string
                  description: 重排提示
                  example: 美国首都是哪里?
                documents:
                  type: array
                  description: 用于重新排序的字符串数组
                  items:
                    type: string
                  example:
                    - 待重排文本1
                    - 待重排文本2
                    - 待重排文本3
                top_n:
                  type: integer
                  description: 返回前N个最匹配结果
                  default: 10
                  example: 10
                retries:
                  type: integer
                  description: 自动重试次数，默认0，表示失败不重试
                  default: 0
                  example: 0
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: object
                required:
                  - model
                  - results
                  - usage
                properties:
                  model:
                    type: string
                    description: 使用的重排模型
                    example: rerank-multilingual-v3.0
                  results:
                    type: array
                    description: 重排序结果列表
                    items:
                      type: object
                      required:
                        - index
                        - relevance_score
                      properties:
                        document:
                          type: string
                          description: 文档内容(当return_documents=true时返回)
                          example: 华盛顿特区是美国的首都
                        index:
                          type: integer
                          description: 原始文档索引
                          minimum: 0
                          example: 0
                        relevance_score:
                          type: number
                          format: float
                          description: 相关性得分(0-1之间)
                          minimum: 0
                          maximum: 1
                          example: 0.89
                  usage:
                    type: object
                    required:
                      - total_tokens
                    properties:
                      total_tokens:
                        type: integer
                        description: 总消耗token数
                        example: 256
                      query_tokens:
                        type: integer
                        description: 查询消耗token数
                        example: 32
                      documents_tokens:
                        type: integer
                        description: 文档消耗token数
                        example: 224
                  metadata:
                    type: object
                    description: 额外的元数据信息
                    additionalProperties: true
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          description: 输入内容超出限制
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/StandardError'
components:
  responses:
    ValidationError:
      description: 参数验证错误
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
                example: validation_error
              message:
                type: string
                example: 参数验证失败
              details:
                type: object
                additionalProperties:
                  type: string
                example:
                  field: 错误描述
    Unauthorized:
      description: 未授权
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
                example: unauthorized
              message:
                type: string
                example: Invalid API key or token
    StandardError:
      description: 标准错误响应
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: 错误代码
          example: invalid_request
        message:
          type: string
          description: 错误信息描述
          example: 请求参数不合法
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API认证token
    apiKeyAuth:
      type: apiKey
      in: header
      name: GeekAI-API-Key
      description: API密钥认证

````