<span id="图纸检索输入与模式"></span>

# Drawing search input and modes

| Field | JSON type/form value | Required | Description |
| --- | --- | --- | --- |
| knowledge_base_id | integer / decimal text | Yes | Positive integer knowledge base ID. |
| drawing_number | string | Condition | Business drawing number. Nonempty values prioritize exact matching, without query or image similarity retrieval. |
| query | string | Condition | Text query; may combine with file. Uses semantic multichannel retrieval only without drawing_number. |
| file | Multipart file | Condition | Image bytes; not supported in JSON. This is not a previously uploaded file_id or query_image_file_id. |
| top_k | integer / decimal text | No | Omission/0 defaults to 8. Semantic maximum 50; negative values rejected. Exact version queries are not truncated by top_k. |

Supply at least one of drawing_number, query, or file. JSON accepts only knowledge_base_id/query/drawing_number/top_k and rejects unknown fields. Multipart uses file. Leading/trailing whitespace is trimmed; drawing numbers also follow shared business-number normalization. Unnormalizable or unmatched numbers return empty exact results without similarity fallback. With both number and image, request boundaries may still validate image/quotas; exact priority does not bypass upload checks.

Body limit 33 MiB. Image files must be nonempty, at most 32 MiB, and detected as image/*. Individual file overflow and whole-body overflow can map to different errors. A 32 MiB limit does not guarantee embedding executability. Images become data URIs and may be compressed over budget, but remain subject to the 4 MiB embedding budget and actual model/binding preprocessing. Failures return ErrPayloadTooLarge. Public URLs are not substituted to bypass limits.

Within the knowledge base's authorized source scope, semantic retrieval combines filename/identifier hints, text, and image retrieval. It aggregates by source_file_id, with one best_hit and at most three supporting_hits. overwrite_current restricts sources to current pointers; keep_versions permits all still-published valid versions. Historical knowledge bases without drawing_current schema may fall back to index search, but exact drawing-number queries fail closed without the current index. keep_versions number queries may return all valid versions and mark the current pointer with default_version. Not every hit is current.

top_k is not a page size. No offset/cursor exists, and count is not a total for continued pagination. Identifier hints' identifier_route_used does not mean match_mode=exact. Unparsed sources, unavailable indexes, and valid empty knowledge bases are different results. A 503 is not zero hits.

Optional JSON query/drawing_number null values become empty strings; top_k=null also uses the default. At least one query condition is still required. Form text null is not JSON null.
