# Chunk 与 Evidence API ## 接口说明 这组接口用于把搜索结果落到可读的证据对象。 - `GET /api/archives/{archive_uid}` 返回 archive 级详情。 - `GET /api/archives/{archive_uid}/chunks` 返回该 archive 下的 chunk 列表。 - `GET /api/archives/{archive_uid}/evidence` 返回该 archive 下适合引用/AI 消费的证据列表。 - `GET /api/chunks/{chunk_uid}` 偏底层，返回 chunk 详情和所属 archive 信息。 - `GET /api/evidence/{chunk_uid}` 偏引用与展示，返回 citation、页码标签和证据正文。 其中 archive 接口以 `archive_uid` 为主键，另外两者以 `chunk_uid` 为主键。 ## Archive 详情 ```http GET /api/archives/{archive_uid} ``` ### 请求示例 ```bash curl /api/archives/01KQHVREB6XPYF604RVZAP9NNY ``` ### 成功响应 状态码： ```http 200 OK ``` 响应示例： ```json { "code": 0, "message": "Archive loaded.", "data": { "archive_uid": "01KQHVREB6XPYF604RVZAP9NNY", "title": "1.test", "summary": "This directive, signed by Brent Scowcroft ...", "year": 1992, "author": "Brent Scowcroft", "source": "test/1.test.md", "series": null, "tags": ["National Security", "Policy"], "metadata": { "ai_enrichment": { "provider": "bigmodel" } }, "content": "full normalized archive content ...", "raw": "# 1.test ...", "chunks": [ "01KQHVREB6XPYF604RVZAP9NNY_1_39003", "01KQHVREB6XPYF604RVZAP9NNY_2_12345" ], "chunk_count": 14 } } ``` 说明： - `content` 是归一化后的 archive 正文。 - `raw` 是导入时保存的原始 Markdown。 - `chunks` 是当前 archive 关联的 `chunk_uid` 列表。 - `chunk_count` 方便调用方快速判断档案规模，而不必自己数数组长度。 ### 错误响应 #### archive 不存在 状态码： ```http 404 Not Found ``` ```json { "code": 404, "message": "Archive not found.", "errors": { "archive_uid": "missing_archive_uid" } } ``` ## Archive 下的 Chunk 列表 ```http GET /api/archives/{archive_uid}/chunks ``` ### 请求示例 ```bash curl /api/archives/01KQHVREB6XPYF604RVZAP9NNY/chunks ``` ### 成功响应 状态码： ```http 200 OK ``` 响应示例： ```json { "code": 0, "message": "Archive chunks loaded.", "data": { "archive_uid": "01KQHVREB6XPYF604RVZAP9NNY", "title": "1.test", "summary": "This directive, signed by Brent Scowcroft ...", "source": "test/1.test.md", "author": "Brent Scowcroft", "year": 1992, "series": null, "tags": ["National Security", "Policy"], "chunk_count": 14, "chunks": [ { "chunk_uid": "01KQHVREB6XPYF604RVZAP9NNY_1_39003", "archive_uid": "01KQHVREB6XPYF604RVZAP9NNY", "chunk_index": 1, "page_start": 1, "page_end": 1, "pages": [1], "text": "chunk text...", "length": 300, "embedding_status": 3, "embedding_ref": { "provider": "bigmodel", "model": "embedding-3", "dimensions": 2048 }, "embedding_model": "embedding-3", "embedding_error": null, "search_index_status": 3, "search_index_error": null, "archive": { "archive_uid": "01KQHVREB6XPYF604RVZAP9NNY", "title": "1.test", "summary": "This directive, signed by Brent Scowcroft ...", "year": 1992, "author": "Brent Scowcroft", "source": "test/1.test.md", "series": null, "tags": ["National Security", "Policy"], "metadata": {} } } ] } } ``` 说明： - 这个接口偏底层，适合按 archive 批量读取完整 chunk 数据。 - `chunks` 按 `chunk_index` 升序返回。 ## Archive 级 Evidence 列表 ```http GET /api/archives/{archive_uid}/evidence ``` ### 请求示例 ```bash curl /api/archives/01KQHVREB6XPYF604RVZAP9NNY/evidence ``` ### 成功响应 状态码： ```http 200 OK ``` 响应示例： ```json { "code": 0, "message": "Archive evidence loaded.", "data": { "archive_uid": "01KQHVREB6XPYF604RVZAP9NNY", "title": "1.test", "summary": "This directive, signed by Brent Scowcroft ...", "source": "test/1.test.md", "author": "Brent Scowcroft", "year": 1992, "series": null, "tags": ["National Security", "Policy"], "chunk_count": 14, "evidence": [ { "chunk_uid": "01KQHVREB6XPYF604RVZAP9NNY_1_39003", "chunk_index": 1, "page_start": 1, "page_end": 1, "pages": [1], "page_label": "p. 1", "citation": "1.test | Brent Scowcroft | 1992 | p. 1 | test/1.test.md", "quote": "chunk text...", "length": 300, "embedding_model": "embedding-3", "embedding_status": 3, "search_index_status": 3 } ] } } ``` 说明： - 这个接口偏上层，适合 AI、RAG、引用构造和前端证据列表展示。 - `evidence` 里的每一项都保留了 citation 所需的页码和引用文本。 ## Chunk 详情 ```http GET /api/chunks/{chunk_uid} ``` ### 请求示例 ```bash curl /api/chunks/01KQHVREB6XPYF604RVZAP9NNY_14_97554 ``` ### 成功响应 状态码： ```http 200 OK ``` 响应示例： ```json { "code": 0, "message": "Chunk loaded.", "data": { "chunk_uid": "01KQHVREB6XPYF604RVZAP9NNY_14_97554", "archive_uid": "01KQHVREB6XPYF604RVZAP9NNY", "chunk_index": 14, "page_start": 8, "page_end": 8, "pages": [8], "text": "NSD 45 20 AUG 90 U.S. Policy in Response to the Iraqi Invasion of Kuwait ...", "length": 148, "embedding_status": 3, "embedding_ref": { "provider": "bigmodel", "model": "embedding-3", "dimensions": 2048 }, "embedding_model": "embedding-3", "embedding_error": null, "search_index_status": 3, "search_index_error": null, "archive": { "archive_uid": "01KQHVREB6XPYF604RVZAP9NNY", "title": "1.test", "summary": null, "year": 1992, "author": "Brent Scowcroft", "source": "test/1.test.md", "series": null, "tags": [], "metadata": {} } } } ``` ### 错误响应 #### chunk 不存在 状态码： ```http 404 Not Found ``` ```json { "code": 404, "message": "Chunk not found.", "errors": { "chunk_uid": "missing_chunk_uid" } } ``` ## Evidence 详情 ```http GET /api/evidence/{chunk_uid} ``` ### 请求示例 ```bash curl /api/evidence/01KQHVREB6XPYF604RVZAP9NNY_14_97554 ``` ### 成功响应 状态码： ```http 200 OK ``` 响应示例： ```json { "code": 0, "message": "Evidence loaded.", "data": { "chunk_uid": "01KQHVREB6XPYF604RVZAP9NNY_14_97554", "archive_uid": "01KQHVREB6XPYF604RVZAP9NNY", "title": "1.test", "source": "test/1.test.md", "author": "Brent Scowcroft", "year": 1992, "series": null, "tags": [], "page_start": 8, "page_end": 8, "pages": [8], "page_label": "p. 8", "citation": "1.test | Brent Scowcroft | 1992 | p. 8 | test/1.test.md", "quote": "NSD 45 20 AUG 90 U.S. Policy in Response to the Iraqi Invasion of Kuwait ...", "chunk": { "chunk_index": 14, "length": 148, "embedding_model": "embedding-3", "embedding_status": 3, "search_index_status": 3 } } } ``` ### 错误响应 #### evidence 不存在 状态码： ```http 404 Not Found ``` ```json { "code": 404, "message": "Evidence not found.", "errors": { "chunk_uid": "missing_chunk_uid" } } ```