openapi: 3.0.0

info:
  title: 知识库 OpenAPI
  version: 1.0.0
  description: >-
    ### 功能介绍

    这里是知识库相关openapi。

    ### 接入指引

    调用以下接口需要传递 AccessToken 或者ApiKey，格式如`Authorization: Bearer <token>` 或者 `Authorization: Bearer <ApiKey>`。Token 获取方式参考：https://docs.cloudbase.net/http-api/basic/access-token;

    ApiKey 获取方式参考：https://docs.cloudbase.net/http-api/basic/api-key

    ### HTTP 状态码

    根据返回结果的不同，可能会出现 `2xx`, `4xx`, `5xx` 状态码。

    ### 错误码

    以下列出了该系列 API 特定的错误码，完整列表参考：https://docs.cloudbase.net/error-code/service

    <table>
      <thead>
        <tr>
          <td>错误码</td>
          <td>含义</td>
        </tr>
      </thead>
      <tr>
        <td>INVALID_PARAMETER</td>
        <td>参数错误</td>
      </tr>
      <tr>
        <td>MISSING_PARAMETER</td>
        <td>缺少参数错误</td>
      </tr>
      <tr>
        <td>RESOURCE_NOTFOUND</td>
        <td>资源不存在</td>
      </tr>
      <tr>
        <td>INVALID_PARAMETER_VALUE</td>
        <td>参数取值错误</td>
      </tr>
      <tr>
        <td>REQUEST_LIMIT_EXCEEDED</td>
        <td>请求的次数超过了频率限制</td>
      </tr>
      <tr>
        <td>SYS_ERR</td>
        <td>内部错误</td>
      </tr>
      <tr>
        <td>FAILED_OPERATION</td>
        <td>操作失败</td>
      </tr>
    </table>

tags:
  - name: 知识库方法
servers:
  - url: https://{envId}.api.tcloudbasegateway.com
    description: TCB openapi endpoint
    variables:
      envId:
        default: "your-envId"
        description: 环境 ID

paths:
  /v1/knowledge/search:
    post:
      tags:
        - 知识库方法
      operationId: search
      summary: 知识库检索文档
      description: 支持指定文件名称检索最相似的文本信息。支持文件名搭配文件元数据的标量字段的 Filter 表达式检索最相似的文本信息。支持仅使用文件元数据的标量字段的 Filter 表达式检索最相似的文本信息。
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchDocSetReq"
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/SearchDocSetRsp"
                  - $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: "code"
          title: "错误码"
        message:
          type: string
          example: "message"
          title: "错误信息"
        requestId:
          type: string
          example: "requestId"
          title: "请求唯一id"
    SearchDocSetReq:
      type: object
      properties:
        collectionView:
          type: string
          example: "ykfty_6fWO"
          title: "知识库ID"
          required: true
        search:
          $ref: "#/components/schemas/DocSearch"
    DocSearch:
      type: object
      properties:
        content:
          type: string
          example: "如何使用云开发"
          title: "搜索的内容"
          required: true
        documentSetName:
          type: array
          items:
            type: string
            example: "xx.md"
            title: "搜索的文件名称"
          required: false
        options:
          $ref: "#/components/schemas/DocOptions"
        filter:
          type: string
          example: "xxx"
          title: "Filter 索引"
          required: false
        limit:
          type: integer
          example: 2
          title: "指定返回最相似的 Top K 的 K 的值"
          required: false
    DocOptions:
      type: object
      properties:
        chunkExpand:
          type: array
          required: false
          items:
            type: integer
            example: 2
            title: "指定返回的文档内容的展开长度"

    SearchDocSetRsp:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/SearchDocSetRspData"
        requestId:
          type: string
          example: "reqid"
          title: "请求唯一id"
    SearchDocSetRspData:
      type: object
      properties:
        documents:
          type: array
          items:
            $ref: "#/components/schemas/KnowledgeDoc"
    KnowledgeDoc:
      type: object
      properties:
        score:
          type: number
          example: 0.9
          title: "搜索的分数"
          format: float
        data:
          $ref: "#/components/schemas/DocData"
        documentSet:
          $ref: "#/components/schemas/KnowledgeSearchDoc"
    DocData:
      type: object
      properties:
        text:
          type: string
          example: "xxx"
          title: "文档内容"
        startPos:
          type: integer
          example: 0
          title: "匹配的开始位置"
          format: int32
        endPos:
          type: integer
          example: 10
          title: "匹配的结束位置"
          format: int32
        pre:
          type: array
          items:
            type: string
            example: "xxx"
            title: "匹配的前置内容"
        next:
          type: array
          items:
            type: string
            example: "xxx"
            title: "匹配的后置内容"
        paragraphTitle:
          type: string
          example: "xxx"
          title: "匹配的段落标题"
        allParentParagraphTitles:
          type: array
          items:
            type: string
            example: "xxx"
            title: "匹配的所有父级段落标题"

    KnowledgeSearchDoc:
      type: object
      properties:
        documentSetId:
          type: string
          example: "xxx"
          title: "文档集id"
        documentSetName:
          type: string
          example: "xxx"
          title: "文档集名称"
        author:
          type: string
          example: "xxx"
          title: "文档集作者"
        fileTitle:
          type: string
          example: "xxx"
          title: "文档集标题"
        fileMetaData:
          type: string
          example: '{"title":"标题","name":"名称"}'
          title: "文档集元数据"

  securitySchemes:
    JWTAuth:
      type: http
      scheme: Bearer
      description: 环境 ID 所对应的 token，使用登录认证(v2)获取
    APIKey:
      type: apiKey
      in: header
      name: Authorization
      description: TC3-HMAC-SHA256开头的腾讯云 3.0 版签名，将 Timestamp 和 Token 拼接在签名最后

security:
  - JWTAuth: []
  - APIKey: []