Focowiki

简体中文

English

简体中文

English

Appearance

搜索文件 ​

接口说明 ​

按路径、标题、章节、Markdown 正文、元数据和可选文件关系查找当前可读取文件。使用结果内容前必须先读取返回的文件。

接口信息 ​

字段值
方法GET
路径/openapi/v2/knowledge-bases/{knowledgeBaseId}/files/search
Operation IDsearchGeneratedFiles
鉴权Bearer OpenAPI key

入参 ​

名称位置必填类型示例说明
knowledgeBaseIdpath是stringknowledge-base-11111111-1111-4111-8111-111111111111知识库 API 返回的知识库标识。
queryquery是stringHow do I configure and verify the knowledge base deployment?一个完整独立的自然语言问题或搜索文本。Unicode 和空白规范化后必须包含 2 到 512 个字素簇、最多 2048 个 UTF-8 字节，并且不能包含不安全控制字符。结果是来源文件，使用其中内容作为证据前必须读取正文。
scopequery否all | path | metadataall可用的证据字段范围。path 执行精确路径和有正文依据的标题检索，metadata 执行词法元数据检索，all 使用当前模式启用的全部证据类型。
fileKindquery否all | pagepage可读取文件类型筛选。搜索只返回由上传文件生成且当前生效的 Markdown page 文件。all 会移除显式类型条件，但当前返回相同的 page 文件集合。
modequery否file | graph | hybridhybrid搜索策略。file 搜索文件数据和语义相似内容，graph 沿文件关系和图语义信号查找，hybrid 合并两者。scope 用于缩小搜索字段范围。每条结果仍然是可读取的来源文件。
graphDepthquery否0 | 1 | 21图搜索和混合搜索结果返回的关系上下文深度。0 只返回起点图引用而不返回关系，1 包含直接关系，2 可以在 graphFanout 范围内包含第二层关系；超过部署上限时返回 422。
graphFanoutquery否integer10在请求的关系深度范围内，每个图搜索结果最多返回的关系记录总数。省略时使用当前部署配置；超过部署上限时返回 422。
okfStatusquery否draft | stable | deprecateddraft按规范化 OKF 文档状态筛选；显式提供无效状态的文件不会匹配。
okfTrustTierquery否unverified | machine-confirmed | human-reviewedunverified按规范化 OKF 验证层级筛选；显式提供格式错误验证信息的文件不会匹配。
okfFreshnessquery否fresh | stalefresh按请求日期筛选新鲜或过期文件；缺少有效 stale_after 的文件不会匹配。
rerankquery否booleantrue本次搜索是否请求可选的来源候选重排。
rerankTopKquery否integer50启用重排时参与处理的非精确候选数量。
rerankScoreThresholdquery否number0启用重排时非精确候选需要达到的最低有效分数。
limitquery否integer10本次请求实际采用的最大返回数量。
cursorquery否stringcursor_123当前搜索返回的分页标记。只能在查询词、筛选条件、可读取知识库版本和排序设置不变时继续使用。

请求体 ​

这个接口没有请求体。

请求示例 ​

bash
curl -X GET "https://openapi.example.com/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/search?query=How+do+I+configure+and+verify+the+knowledge+base+deployment%3F&scope=all&fileKind=page&mode=hybrid&graphDepth=1&graphFanout=10&limit=10" \
  -H "Authorization: Bearer <openapi-key>"

成功响应 ​

200 ​

返回与查询匹配并按相关度排序的当前可读取文件。

字段必填类型说明
activeContentRevision是object当前可读取知识库内容的修订号。
query是object本次使用的查询词和选项。
items是array<FileSearchResult>当前分页中的记录。
nextCursor是string | null当前搜索接口返回的分页标记。只能在查询词、筛选条件和可读取知识库版本不变时继续使用；被拒绝时请移除 cursor 并重新搜索。
searchStatus是ok | no_candidatesok 表示已返回搜索结果。no_candidates 表示当前查询没有匹配文件。依赖服务失败时使用文档中的 503 或 504 错误结构。
searchMode是file | graph | hybrid本次响应实际使用的搜索模式。
semanticStatus是object本次响应中可选语义搜索通道的可用状态和安全原因码。
evidenceStatus是object本次响应中已完成或降级的检索证据类型。
rerankerStatus是object可选重排是否已应用、跳过、不可用或降级。
graphStatus是available | index_unavailable | disabled_for_file_mode本次响应中的关系搜索可用状态。仅搜索文件时返回 disabled_for_file_mode。
graphSummary是object本次响应使用的文件关系摘要。
resultSummary是object当前结果的数量、分页情况和说明。
message否string | null没有匹配文件或搜索暂不可用时返回的状态说明。
nextActions否array<string>继续探索时建议执行的文件读取或关系查询。

成功响应示例 ​

json
{
  "activeContentRevision": 1,
  "query": {
    "query": "How do I configure and verify the knowledge base deployment?",
    "normalizedQuery": "How do I configure and verify the knowledge base deployment?",
    "scope": "all",
    "fileKind": "page",
    "mode": "hybrid",
    "graphDepth": 1,
    "graphFanout": 10,
    "okfStatus": null,
    "okfTrustTier": null,
    "okfFreshness": null,
    "rerank": false,
    "rerankTopK": null,
    "rerankScoreThreshold": null,
    "limit": 10,
    "cursorProvided": false
  },
  "items": [
    {
      "activeContentRevision": 1,
      "fileId": "source-file-11111111-1111-4111-8111-111111111111",
      "knowledgeBaseId": "knowledge-base-11111111-1111-4111-8111-111111111111",
      "sourceFileId": "source-file-11111111-1111-4111-8111-111111111111",
      "path": "pages/guide.md",
      "fileKind": "page",
      "title": "Verified guide",
      "description": null,
      "tags": [
        "guide",
        "policy"
      ],
      "frontmatter": {
        "okf_version": "0.2",
        "type": "Guide",
        "title": "Verified guide",
        "tags": [
          "guide",
          "policy"
        ],
        "sources": [
          {
            "id": "source-a",
            "resource": "references/source-a.md"
          }
        ],
        "generated": {
          "by": "publisher:example",
          "at": "2026-06-17T00:00:00Z"
        },
        "verified": [
          {
            "by": "human:reviewer",
            "at": "2026-06-17T01:00:00Z"
          }
        ],
        "status": "stable",
        "stale_after": "2026-12-31"
      },
      "okfSignals": {
        "effectiveStatus": "stable",
        "trustTier": "human-reviewed",
        "isStale": false,
        "staleAfter": "2026-12-31",
        "generatedAt": "2026-06-17T00:00:00.000Z",
        "generatedAtSource": "generated",
        "latestVerifiedAt": "2026-06-17T01:00:00.000Z",
        "sourceCount": 1
      },
      "matchedFields": [
        "content"
      ],
      "evidenceTypes": [
        "content"
      ],
      "sourceExcerpt": "Configure the deployment, then verify service health and search readiness.",
      "score": 9,
      "contentAvailable": true,
      "matchType": "file_direct",
      "readActions": {
        "fileDetailById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111",
        "fileContentById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111/content",
        "fileContentByPath": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Fguide.md",
        "relatedFilesById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-11111111-1111-4111-8111-111111111111/related",
        "graphExpansionByFileId": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/graph/expand?fileId=source-file-11111111-1111-4111-8111-111111111111",
        "sourceFileStatusById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-11111111-1111-4111-8111-111111111111"
      },
      "graphContext": {
        "graphRef": "_graph/by-file/handbook/guide.json",
        "depth": 1,
        "seedSourceFileId": "source-file-11111111-1111-4111-8111-111111111111",
        "relationships": [
          {
            "activeContentRevision": 1,
            "fileId": "source-file-22222222-2222-4222-8222-222222222222",
            "sourceFileId": "source-file-22222222-2222-4222-8222-222222222222",
            "path": "pages/reference.md",
            "title": "Reference",
            "relationType": "same_specific_subject",
            "direction": "outgoing",
            "fromFileId": "source-file-11111111-1111-4111-8111-111111111111",
            "relationshipDepth": 1,
            "reason": "Both files share body-derived subjects.",
            "contentAvailable": true,
            "readActions": {
              "fileDetailById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-22222222-2222-4222-8222-222222222222",
              "fileContentById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-22222222-2222-4222-8222-222222222222/content",
              "fileContentByPath": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/content?path=pages%2Freference.md",
              "relatedFilesById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/files/source-file-22222222-2222-4222-8222-222222222222/related",
              "graphExpansionByFileId": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/graph/expand?fileId=source-file-22222222-2222-4222-8222-222222222222",
              "sourceFileStatusById": "/openapi/v2/knowledge-bases/knowledge-base-11111111-1111-4111-8111-111111111111/source-files/source-file-22222222-2222-4222-8222-222222222222"
            }
          }
        ],
        "graphPaths": [
          "_graph/by-file/handbook/guide.json",
          "_graph/by-file/reference.json"
        ]
      }
    }
  ],
  "nextCursor": null,
  "searchStatus": "ok",
  "searchMode": "hybrid",
  "semanticStatus": {
    "state": "ready",
    "safeCode": null
  },
  "evidenceStatus": {
    "completedFamilies": [
      "exact_path",
      "exact_title",
      "lexical",
      "jieba",
      "content_vector",
      "entity_vector",
      "relationship_vector",
      "community_vector",
      "file_graph",
      "file_relationship"
    ],
    "degradedFamilies": []
  },
  "rerankerStatus": {
    "state": "skipped",
    "safeCode": "RERANKER_DISABLED"
  },
  "graphStatus": "available",
  "graphSummary": {
    "available": true,
    "indexedDocumentCount": 24,
    "indexedRelationshipCount": 86,
    "depth": 1,
    "fanout": 10
  },
  "resultSummary": {
    "resultCount": 1,
    "hasMore": false,
    "sort": [
      "relevance_desc",
      "logical_path_asc",
      "source_file_id_asc"
    ],
    "meaning": "The query matched readable files. Read the returned files and related files before using their content."
  }
}

错误码 ​

下表列出这个接口已声明的全部错误响应。

HTTP 状态错误码说明
401UNAUTHORIZEDBearer API key 缺失、格式错误、未知、已撤销或已删除。
404NOT_FOUND请求的资源不存在。
422VALIDATION_ERROR请求未通过校验。
429RATE_LIMITED请求超过当前配置的速率限制。
500INTERNAL_ERRORAPI 遇到内部错误。
503DATABASE_REPOSITORY_UNAVAILABLE当前接口所需的数据暂时不可用。
503SEARCH_UNAVAILABLE搜索服务暂时不可用。
503SEARCH_OVERLOADED搜索服务当前负载过高。
504SEARCH_TIMEOUT搜索超过当前配置的响应时限。

校验详情码 ​

收到 422 VALIDATION_ERROR 时，读取 error.details.code。此接口可能返回：

  • FILE_SEARCH_QUERY_REQUIRED
  • FILE_SEARCH_QUERY_TOO_SHORT
  • FILE_SEARCH_QUERY_TOO_LONG
  • INVALID_FILE_SEARCH_QUERY
  • INVALID_FILE_SEARCH_SCOPE
  • INVALID_FILE_SEARCH_KIND
  • INVALID_FILE_SEARCH_MODE
  • INVALID_FILE_SEARCH_GRAPH_DEPTH
  • INVALID_FILE_SEARCH_GRAPH_FANOUT
  • INVALID_FILE_SEARCH_OKF_STATUS
  • INVALID_FILE_SEARCH_OKF_TRUST_TIER
  • INVALID_FILE_SEARCH_OKF_FRESHNESS
  • INVALID_FILE_SEARCH_LIMIT
  • INVALID_FILE_SEARCH_RERANK_CONTROLS

后续操作 ​