7.2 KiB
7.2 KiB
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 详情
GET /api/archives/{archive_uid}
请求示例
curl <APIdomain>/api/archives/01KQHVREB6XPYF604RVZAP9NNY
成功响应
状态码：
200 OK
响应示例：
{
"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"
}
},
"chunks": [
"01KQHVREB6XPYF604RVZAP9NNY_1_39003",
"01KQHVREB6XPYF604RVZAP9NNY_2_12345"
],
"chunk_count": 14
}
}
说明：
chunks是当前 archive 关联的chunk_uid列表。chunk_count方便调用方快速判断档案规模，而不必自己数数组长度。
错误响应
archive 不存在
状态码：
404 Not Found
{
"code": 404,
"message": "Archive not found.",
"errors": {
"archive_uid": "missing_archive_uid"
}
}
Archive 下的 Chunk 列表
GET /api/archives/{archive_uid}/chunks
请求示例
curl <APIdomain>/api/archives/01KQHVREB6XPYF604RVZAP9NNY/chunks
成功响应
状态码：
200 OK
响应示例：
{
"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 列表
GET /api/archives/{archive_uid}/evidence
请求示例
curl <APIdomain>/api/archives/01KQHVREB6XPYF604RVZAP9NNY/evidence
成功响应
状态码：
200 OK
响应示例：
{
"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 详情
GET /api/chunks/{chunk_uid}
请求示例
curl <APIdomain>/api/chunks/01KQHVREB6XPYF604RVZAP9NNY_14_97554
成功响应
状态码：
200 OK
响应示例：
{
"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 不存在
状态码：
404 Not Found
{
"code": 404,
"message": "Chunk not found.",
"errors": {
"chunk_uid": "missing_chunk_uid"
}
}
Evidence 详情
GET /api/evidence/{chunk_uid}
请求示例
curl <APIdomain>/api/evidence/01KQHVREB6XPYF604RVZAP9NNY_14_97554
成功响应
状态码：
200 OK
响应示例：
{
"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 不存在
状态码：
404 Not Found
{
"code": 404,
"message": "Evidence not found.",
"errors": {
"chunk_uid": "missing_chunk_uid"
}
}