Cognee API 完整使用文档（含分类、调用顺序、curl 示例、文件样本、一键脚本及异常码）

本文档基于 Cognee OpenAPI 3.1.0 规范编写，整合了 API 功能分类、标准化使用流程、各步骤 curl 调用示例、文件内容样本、一键测试 Shell 脚本及接口异常码对照表，适用于 PDF 问答系统等典型业务场景，可直接用于开发落地。

核心说明 ：所有业务接口均需通过 Bearer Token 或 Cookie Auth（auth_token） 鉴权，仅用户注册/登录接口无需鉴权。文档中涉及的占位符（如 <your-xxx>）需替换为实际环境参数。

一、API 功能分类介绍

按核心功能模块划分，Cognee API 共分为 8 大类，各类接口的核心作用、关键参数、支持文件格式、内容样本及标准输出示例如下：

1. 认证与用户管理类 API

核心作用：用户注册、登录、信息查询与修改，获取鉴权凭证（Bearer Token）。

接口路径	请求方法	核心功能	关键参数	curl 调用示例	标准输出示例
/api/v1/auth/register	POST	注册新用户	email、password	curl -X POST "http:///api/v1/auth/register" -H "Content-Type: application/json" -d '{"email":"your-email@example.com","password":"your-password"}'	json {"status": "success", "message": "User registered successfully", "user_id": "usr-123456"}
/api/v1/auth/login	POST	用户登录，获取 Bearer Token	username（即 email）、password	curl -X POST "http:///api/v1/auth/login" -H "Content-Type: application/x-www-form-urlencoded" -d "username=your-email@example.com&password=your-password"	json {"status": "success", "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600}
/api/v1/auth/me	GET	获取当前登录用户信息	-（需 Bearer Token）	curl -X GET "http:///api/v1/auth/me" -H "Authorization: Bearer "	json {"id": "usr-123456", "email": "your-email@example.com", "created_at": "2025-12-31T00:00:00Z"}
/api/v1/auth/logout	POST	用户登出，失效当前凭证	-（需 Bearer Token）	curl -X POST "http:///api/v1/auth/logout" -H "Authorization: Bearer "	json {"status": "success", "message": "User logged out successfully"}
/api/v1/users/me	PATCH	修改当前用户信息（如密码）	password、email（可选）	curl -X PATCH "http:///api/v1/users/me" -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"password":"new-password"}'	json {"status": "success", "message": "User info updated successfully"}

2. 系统配置类 API

核心作用：配置 LLM（大语言模型）、向量数据库等核心依赖，是知识图谱构建的前置条件。

接口路径	请求方法	核心功能	关键参数	curl 调用示例	标准输出示例
/api/v1/settings	GET	获取当前系统配置	-（需 Bearer Token）	curl -X GET "http:///api/v1/settings" -H "Authorization: Bearer "	json {"llm": {"provider": "gemini", "model": "gemini-pro", "apiKey": "******"}, "vector_db": {"provider": "lancedb", "url": "your-lancedb-url", "apiKey": "******"}}
/api/v1/settings	POST	保存/更新系统配置	llm（provider、model、apiKey）、vector_db（provider、url、apiKey）	curl -X POST "http:///api/v1/settings" -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"llm":{"provider":"gemini","model":"gemini-pro","apiKey":"your-gemini-api-key"},"vector_db":{"provider":"lancedb","url":"your-lancedb-url","apiKey":"your-lancedb-api-key"}}'	json {"status": "success", "message": "Settings updated successfully"}

3. 数据集管理类 API

核心作用：创建、查询、删除数据集，数据集是组织 PDF 等文档的基本单元，所有数据操作均关联数据集。

接口路径	请求方法	核心功能	关键参数	curl 调用示例	标准输出示例
/api/v1/datasets	POST	创建新数据集	dataset_data.name（数据集名称）	curl -X POST "http:///api/v1/datasets" -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"dataset_data":{"name":"pdf-qa-dataset"}}'	json {"id": "ds-123456", "name": "pdf-qa-dataset", "created_at": "2025-12-31T00:00:00Z", "status": "empty"}
/api/v1/datasets	GET	查询当前用户可访问的所有数据集	-（需 Bearer Token）	curl -X GET "http:///api/v1/datasets" -H "Authorization: Bearer "	json {"datasets": [{"id": "ds-123456", "name": "pdf-qa-dataset", "created_at": "2025-12-31T00:00:00Z", "status": "empty"}]}
/api/v1/datasets/{dataset_id}	DELETE	删除指定数据集（含所有数据和图谱）	dataset_id（路径参数，UUID）	curl -X DELETE "http:///api/v1/datasets/" -H "Authorization: Bearer "	json {"status": "success", "message": "Dataset deleted successfully"}
/api/v1/datasets/{dataset_id}/data	GET	查询指定数据集内的所有数据项	dataset_id（路径参数）	curl -X GET "http:///api/v1/datasets//data" -H "Authorization: Bearer "	json {"data_items": [{"id": "dt-123456", "name": "tech-doc.pdf", "type": "pdf", "uploaded_at": "2025-12-31T00:00:00Z"}]}
/api/v1/datasets/status	GET	查询数据集的处理状态（如构建图谱中/完成）	dataset（数据集 UUID 列表，查询参数）	curl -X GET "http:///api/v1/datasets/status?dataset=" -H "Authorization: Bearer "	json {"statuses": [{"dataset_id": "ds-123456", "status": "DATASET_PROCESSING_COMPLETED", "processed_at": "2025-12-31T00:10:00Z"}]}

4. 数据接入与维护类 API

核心作用：上传 PDF 等文档、更新/删除已有数据，是原始数据进入系统的入口。

支持文件格式 ：PDF（.pdf）、纯文本（.txt）、Markdown（.md）、Word（.docx）、Excel（.xlsx）

接口路径	请求方法	核心功能	关键参数	curl 调用示例（含多格式文件示例）	文件内容样本	标准输出示例
/api/v1/add	POST	上传文件/URL 到指定数据集	data（multipart 格式文件列表）、datasetId/datasetName	单 PDF 文件 ： curl -X POST "http:///api/v1/add" -H "Authorization: Bearer " -F "data=@/path/to/tech-doc.pdf" -F "datasetId=" 多格式混合 ： curl -X POST "http:///api/v1/add" -H "Authorization: Bearer " -F "data=@/path/to/<guide.md>" -F "data=@/path/to/data-sheet.xlsx" -F "datasetName=pdf-qa-dataset"	PDF/Word 样本 （技术文档主题）： # 认知型 RAG 技术白皮书 ## 1. 核心定义 认知型 RAG 是结合知识图谱与检索增强生成的 AI 技术，能提升问答的准确性与可解释性。 ## 2. 关键组件 - 文档解析模块：支持 PDF、Word 等多格式 - 知识图谱构建模块：基于 Cognee 实现实体关系抽取 Markdown 样本 ： markdown<br># RAG 部署指南<br>## 环境依赖<br>- Python 3.10+<br>- Cognee 0.12.0<br>## 部署步骤<br>1. 安装依赖包<br>2. 配置 Gemini API Key<br> Excel 样本 （数据清单）：	文档名称
/api/v1/update	PATCH	更新数据集内的指定数据项	data_id、dataset_id（查询参数）、新 data 文件	curl -X PATCH "http:///api/v1/update?data_id=&dataset_id=" -H "Authorization: Bearer " -F "data=@/path/to/new-tech-doc.docx"	更新后 Word 样本 ： # 认知型 RAG 技术白皮书（V2.0） ## 1. 核心定义 认知型 RAG 是结合知识图谱、检索增强生成与大语言模型的 AI 技术，能提升问答的准确性、可解释性与时效性。 ## 2. 关键组件 - 文档解析模块：支持 PDF、Word、图片 OCR - 知识图谱构建模块：基于 Cognee 实现实体关系抽取 - 问答生成模块：基于 Gemini Pro 优化	json {"status": "success", "message": "Data item updated successfully", "data_item": {"id": "dt-123456", "name": "new-tech-doc.docx", "type": "docx", "updated_at": "2025-12-31T00:05:00Z"}}
/api/v1/datasets/{dataset_id}/data/{data_id}	DELETE	删除数据集内的单个数据项	dataset_id、data_id（均为路径参数）	curl -X DELETE "http:///api/v1/datasets//data/" -H "Authorization: Bearer "	-	json {"status": "success", "message": "Data item deleted successfully"}

5. 知识图谱构建类 API

核心作用：将原始文档转化为结构化知识图谱（实体+关系），是 Cognee 的核心能力，为后续检索问答提供支撑。

支持本体文件格式 ：OWL（.owl）、RDF/XML（.rdf）

接口路径	请求方法	核心功能	关键参数	curl 调用示例（含本体文件示例）	本体文件内容样本	标准输出示例
/api/v1/cognify	POST	对数据集执行认知处理，生成知识图谱	dataset_ids/datasets、run_in_background（是否异步）、custom_prompt（自定义提示词）	curl -X POST "http:///api/v1/cognify" -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"dataset_ids":[""],"run_in_background":true,"custom_prompt":"Extract technical concepts and their relationships from the document."}'	-	json {"status": "success", "message": "Cognify task started", "task_id": "tk-123456"}
/api/v1/datasets/{dataset_id}/graph	GET	查询指定数据集的知识图谱结构（节点+关系）	dataset_id（路径参数）	curl -X GET "http:///api/v1/datasets//graph" -H "Authorization: Bearer "	图谱返回样本 （JSON 格式）： { "nodes": [{"id": "1", "label": "认知型 RAG", "type": "技术"}, {"id": "2", "label": "知识图谱", "type": "组件"}], "edges": [{"source": "1", "target": "2", "relation": "包含"}] }	json {"nodes": [{"id": "n-1", "label": "认知型 RAG", "type": "AI技术", "properties": {}}, {"id": "n-2", "label": "知识图谱", "type": "组件", "properties": {}}], "edges": [{"id": "e-1", "source": "n-1", "target": "n-2", "relation": "包含"}]}
/api/v1/ontologies	POST	上传本体文件，标准化图谱构建	ontology_key、ontology_file（OWL/RDF 文件）	OWL 文件示例 ： curl -X POST "http:///api/v1/ontologies" -H "Authorization: Bearer " -F "ontology_key=tech-ontology" -F "ontology_file=@/path/to/tech-concepts.owl" RDF 文件示例 ： curl -X POST "http:///api/v1/ontologies" -H "Authorization: Bearer " -F "ontology_key=data-model" -F "ontology_file=@/path/to/data-model.rdf"	OWL 文件样本 （核心片段）： xml<br><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:owl="http://www.w3.org/2002/07/owl#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"><br> <owl:Class rdf:ID="AI技术"/><br> <owl:Class rdf:ID="RAG技术"><br> <rdfs:subClassOf rdf:resource="#AI技术"/><br> </owl:Class><br></rdf:RDF><br> RDF 文件样本 （核心片段）： xml<br><rdf:Description rdf:about="http://example.org/tech/CognitiveRAG"><br> <rdf:type rdf:resource="http://example.org/ontology#RAG技术"/><br> <hasComponent rdf:resource="http://example.org/tech/KnowledgeGraph"/><br></rdf:Description><br>	json {"status": "success", "message": "Ontology uploaded successfully", "ontology_key": "tech-ontology"}

6. 检索与问答类 API

核心作用：基于知识图谱进行语义检索、生成问答结果，是业务输出的核心环节。

可视化输出格式 ：HTML（.html）

接口路径	请求方法	核心功能	关键参数	curl 调用示例（含可视化文件示例）	输出内容样本	标准输出示例
/api/v1/search	POST	执行多类型语义检索（核心业务接口）	search_type（检索类型）、dataset_ids、query（用户提问）、top_k（返回结果数）	curl -X POST "http:///api/v1/search" -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"search_type":"GRAPH_COMPLETION","dataset_ids":[""],"query":"认知型 RAG 的核心组件有哪些？","top_k":10}'	检索结果样本 （JSON 格式）： { "query": "认知型 RAG 的核心组件有哪些？", "results": [{"content": "文档解析模块、知识图谱构建模块、问答生成模块", "source": "tech-doc.pdf", "confidence": 0.95}], "graph_evidence": [{"source_node": "认知型 RAG", "target_node": "知识图谱构建模块", "relation": "包含"}] }	json {"query": "认知型 RAG 的核心组件有哪些？", "search_type": "GRAPH_COMPLETION", "results": [{"content": "文档解析模块、知识图谱构建模块、问答生成模块", "source": "tech-doc.pdf", "source_id": "dt-123456", "confidence": 0.95, "graph_evidence": [{"source_node": "n-1", "target_node": "n-2", "relation": "包含"}]}]}
/api/v1/responses/	POST	OpenAI 兼容问答接口，支持函数调用	input（用户提问）、model（模型名称）	curl -X POST "http:///api/v1/responses/" -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"input":"认知型 RAG 的核心组件有哪些？","model":"cognee-v1"}'	问答结果样本 （JSON 格式）： { "id": "resp-123", "object": "chat.completion", "choices": [{"message": {"role": "assistant", "content": "认知型 RAG 的核心组件包含三大模块：1. 文档解析模块，支持 PDF、Word 等多格式文件解析；2. 知识图谱构建模块，基于 Cognee 实现实体与关系的自动抽取；3. 问答生成模块，结合 Gemini Pro 优化回复的流畅度与准确性。"}}] }	json {"id": "resp-123456", "object": "chat.completion", "created": 1735689600, "model": "cognee-v1", "choices": [{"index": 0, "message": {"role": "assistant", "content": "认知型 RAG 的核心组件包含三大模块：1. 文档解析模块，支持 PDF、Word 等多格式文件解析；2. 知识图谱构建模块，基于 Cognee 实现实体与关系的自动抽取；3. 问答生成模块，结合 Gemini Pro 优化回复的流畅度与准确性。"}, "finish_reason": "stop"}]}
/api/v1/visualize	GET	生成知识图谱可视化 HTML 文件	dataset_id（查询参数）	curl -X GET "http:///api/v1/visualize?dataset_id=" -H "Authorization: Bearer " -o graph-visualization.html	HTML 可视化样本 （核心片段）： html<br><!DOCTYPE html><html><body><div id="graph-container"><svg width="800" height="600"><g><circle cx="400" cy="300" r="50" fill="#4285F4" /><text x="400" y="305" text-anchor="middle" fill="white">认知型 RAG</text></g></svg></div></body></html><br>	（直接输出 HTML 文件内容，可保存为本地 .html 文件打开）

7. 权限与租户管理类 API

核心作用：多租户隔离、角色权限分配，适用于团队/企业级部署场景。

接口路径	请求方法	核心功能	关键参数	curl 调用示例	标准输出示例
/api/v1/permissions/tenants	POST	创建新租户	tenant_name（查询参数）	curl -X POST "http:///api/v1/permissions/tenants?tenant_name=team-tenant" -H "Authorization: Bearer "	json {"status": "success", "tenant_id": "tn-123456", "tenant_name": "team-tenant"}
/api/v1/permissions/roles	POST	创建角色	role_name（查询参数）	curl -X POST "http:///api/v1/permissions/roles?role_name=editor" -H "Authorization: Bearer "	json {"status": "success", "role_id": "rl-123456", "role_name": "editor"}
/api/v1/permissions/datasets/{principal_id}	POST	给用户/角色分配数据集权限	principal_id（路径参数）、permission_name（查询参数）、dataset_ids（请求体）	curl -X POST "http:///api/v1/permissions/datasets/?permission_name=write" -H "Authorization: Bearer " -H "Content-Type: application/json" -d '[""]'	json {"status": "success", "message": "Permissions assigned successfully"}

8. 其他辅助类 API

核心作用：服务健康检查、数据同步、笔记本管理等辅助功能。

接口路径	请求方法	核心功能	curl 调用示例	标准输出示例
/health	GET	服务健康检查（存活探针）	curl -X GET "http:///health"	json {"status": "healthy", "version": "0.5.1-local", "uptime": 3600}
/api/v1/sync	POST	将本地数据同步到 Cognee Cloud	curl -X POST "http:///api/v1/sync" -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"dataset_ids":[""]}'	json {"status": "success", "message": "Sync task started", "task_id": "sy-123456"}
/api/v1/sync/status	GET	查询同步任务状态	curl -X GET "http:///api/v1/sync/status" -H "Authorization: Bearer "	json {"tasks": [{"task_id": "sy-123456", "status": "completed", "synced_datasets": ["ds-123456"]}]}

二、常规使用顺序（以 PDF 问答系统为例）

以下流程覆盖从环境初始化到业务问答输出的全链路，按步骤执行即可完成 PDF 问答系统的核心功能落地。

阶段 1：初始化准备（首次部署必做）

1. 用户注册 ：调用 /api/v1/auth/register 接口创建用户，获取注册成功的用户信息。

2. 用户登录 ：调用 /api/v1/auth/login 接口，获取 access_token（后续所有接口需携带此 Token）。

3. 系统配置 ：调用 /api/v1/settings（GET）查看当前配置；调用 /api/v1/settings（POST）配置 LLM 和向量数据库（如 Gemini + LanceDB），此为后续所有操作的基础。

阶段 2：数据集与数据接入

1. 创建数据集 ：调用 /api/v1/datasets（POST）接口，传入数据集名称（如 pdf-qa-dataset），获取 dataset_id（核心标识，后续需频繁使用）。

2. 上传 PDF 数据 ：调用 /api/v1/add（POST）接口，传入 datasetId 和 PDF 文件列表，将原始文档接入数据集。

3. 验证上传结果 ：调用 /api/v1/datasets/{dataset_id}/data（GET）接口，确认 PDF 文件已成功上传并关联到数据集。

阶段 3：知识图谱构建

1. 执行认知处理 ：调用 /api/v1/cognify（POST）接口，传入 dataset_ids，建议设置 run_in_background=true（异步处理大文件，避免接口超时）。

2. 查询处理状态 ：调用 /api/v1/datasets/status（GET）接口，传入 dataset 列表，持续查询直到状态变为 DATASET_PROCESSING_COMPLETED（处理完成）。

3. 验证图谱生成 ：调用 /api/v1/datasets/{dataset_id}/graph（GET）接口，查看知识图谱的 nodes（实体）和 edges（关系），确认图谱构建成功。

阶段 4：检索与问答（业务核心）

1. 执行语义检索 ：调用 /api/v1/search（POST）接口，推荐选择 search_type=GRAPH_COMPLETION（基于知识图谱的深度问答），传入用户提问（如"认知型 RAG 的核心组件有哪些？"），获取检索结果。

2. 生成流畅问答结果 （可选）：若需更自然的回复，调用 /api/v1/responses/（POST）接口，传入用户提问，基于检索结果生成 OpenAI 兼容格式的回复。

3. 图谱可视化 （可选）：调用 /api/v1/visualize（GET）接口，生成知识图谱的 HTML 可视化文件，用于展示和分析实体关系。

阶段 5：数据维护与权限管理（可选）

1. 数据维护 ：更新数据：调用 /api/v1/update（PATCH）接口，传入 data_id、dataset_id 和新文件，更新后需重新执行 cognify 同步图谱；删除数据：调用 /api/v1/datasets/{dataset_id}/data/{data_id}（DELETE）接口，删除单个数据项。

2. 权限管理 （团队场景）：创建租户：调用 /api/v1/permissions/tenants（POST）创建团队租户；分配角色：调用 /api/v1/permissions/roles（POST）创建角色，再调用 /api/v1/permissions/users/{user_id}/roles（POST）给用户分配角色；共享数据集：调用 /api/v1/permissions/datasets/{principal_id}（POST）接口，给角色分配数据集的读写权限。

三、关键注意事项

1. 参数必传性 ：/api/v1/add 和 /api/v1/cognify 接口必须传入 datasetId 或 datasetName（二选一），否则会返回 400 Bad Request 错误。

2. 异步处理优先级 ：处理大体积 PDF（如 100MB+）时，务必将 /api/v1/cognify 的 run_in_background 设置为 true，避免接口超时，通过 /api/v1/datasets/status 轮询状态。

3. 检索类型选择建议 ：知识图谱深度问答 → GRAPH_COMPLETION；基础文档分块 RAG 问答 → RAG_COMPLETION；仅获取文档分块（自定义 LLM 调用） → CHUNKS。

4. 鉴权凭证有效期 ：Bearer Token 存在有效期（默认需修改源码配置，参考前文），过期后需重新调用 /api/v1/auth/login 获取新 Token。

5. 文件格式限制：上传文件需符合支持的格式列表，非支持格式会返回 415 Unsupported Media Type 错误。

四、附录 1：常用参数说明

• dataset_id：数据集唯一标识（UUID），创建数据集后由接口返回，后续所有数据/图谱操作均需关联此参数。

• data_id：单个数据项（如 PDF 文件）的唯一标识（UUID），上传数据后由接口返回，用于更新/删除单个数据。

• search_type：检索类型枚举值，核心可选值：GRAPH_COMPLETION、RAG_COMPLETION、CHUNKS。

• run_in_background：是否异步执行，true 为异步（适合大文件/批量处理），false 为同步（适合小文件/实时处理）。

五、附录 2：一键测试 Shell 脚本

该脚本可自动完成用户登录→创建数据集→上传文件→构建图谱→检索问答的全流程测试，需提前替换占位符并准备测试文件。

#!/bin/bash
# Cognee API 全流程测试脚本
# 请替换以下占位符为实际环境参数
DEPLOY_URL="<your-deploy-url>"
EMAIL="your-email@example.com"
PASSWORD="your-password"
GEMINI_API_KEY="your-gemini-api-key"
LANCEDB_URL="your-lancedb-url"
LANCEDB_API_KEY="your-lancedb-api-key"
TEST_FILE_PATH="/path/to/your/tech-doc.pdf"
QUERY="认知型 RAG 的核心组件有哪些？"

echo "===== 1. 用户登录获取 Token ====="
TOKEN=$(curl -s -X POST "${DEPLOY_URL}/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=${EMAIL}&password=${PASSWORD}" | jq -r '.access_token')
echo "获取到 Token: ${TOKEN:0:20}..."

echo -e "\n===== 2. 配置系统参数 ====="
curl -s -X POST "${DEPLOY_URL}/api/v1/settings" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"llm\": {
      \"provider\": \"gemini\",
      \"model\": \"gemini-pro\",
      \"apiKey\": \"${GEMINI_API_KEY}\"
    },
    \"vector_db\": {
      \"provider\": \"lancedb\",
      \"url\": \"${LANCEDB_URL}\",
      \"apiKey\": \"${LANCEDB_API_KEY}\"
    }
  }" && echo "系统配置成功"

echo -e "\n===== 3. 创建数据集 ====="
DATASET_ID=$(curl -s -X POST "${DEPLOY_URL}/api/v1/datasets" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"dataset_data":{"name":"pdf-qa-test-dataset"}}' | jq -r '.id')
echo "创建数据集成功，ID: ${DATASET_ID}"

echo -e "\n===== 4. 上传测试文件 ====="
curl -s -X POST "${DEPLOY_URL}/api/v1/add" \
  -H "Authorization: Bearer ${TOKEN}" \
  -F "data=@${TEST_FILE_PATH}" \
  -F "datasetId=${DATASET_ID}" && echo "文件上传成功"

echo -e "\n===== 5. 执行认知处理构建图谱 ====="
curl -s -X POST "${DEPLOY_URL}/api/v1/cognify" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"dataset_ids\": [\"${DATASET_ID}\"],
    \"run_in_background\": false,
    \"custom_prompt\": \"Extract technical concepts and their relationships\"
  }" && echo "图谱构建成功"

echo -e "\n===== 6. 执行语义检索 ====="
curl -s -X POST "${DEPLOY_URL}/api/v1/search" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"search_type\": \"GRAPH_COMPLETION\",
    \"dataset_ids\": [\"${DATASET_ID}\"],
    \"query\": \"${QUERY}\",
    \"top_k\": 10
  }" | jq '.'

echo -e "\n===== 7. 生成问答结果 ====="
curl -s -X POST "${DEPLOY_URL}/api/v1/responses/" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"input\": \"${QUERY}\",
    \"model\": \"cognee-v1\"
  }" | jq '.'

echo -e "\n===== 全流程测试完成 ====="

脚本使用说明：

1. 安装 jq 工具（用于 JSON 解析）：sudo apt install jq（Linux）或 brew install jq（Mac）。

2. 替换脚本中的占位符为实际参数。

3. 赋予脚本执行权限：chmod +x cognee_test.sh。

4. 运行脚本：./cognee_test.sh。

六、附录 3：接口异常码对照表

异常码	异常类型	对应接口	常见原因	解决方案
400	Bad Request	所有接口	参数缺失/格式错误（如 datasetId 未传、JSON 格式非法）	检查并补充必填参数，确保请求体格式符合要求
401	Unauthorized	所有需鉴权接口	Token 过期/无效/未携带	重新登录获取 Token，请求头中正确携带 Authorization: Bearer <token>
403	Forbidden	权限管理类、数据集操作类接口	无对应资源操作权限（如非数据集所有者执行删除）	联系管理员分配权限，或使用拥有权限的账号调用
404	Not Found	数据集/数据项/任务查询接口	资源 ID 错误（如 dataset_id 不存在）	确认资源 ID 正确性，先通过列表接口查询有效 ID
415	Unsupported Media Type	/api/v1/add /api/v1/update /api/v1/ontologies	上传文件格式不支持（如上传 .ppt 文件）	更换为支持的文件格式（PDF/MD/TXT/DOCX/XLSX/OWL/RDF）
429	Too Many Requests	所有接口	短时间内请求频率过高，触发限流	降低请求频率，或联系管理员调整限流阈值
500	Internal Server Error	所有接口	服务端内部错误（如数据库连接失败、模型调用异常）	查看服务端日志定位问题，重试请求或联系技术支持
503	Service Unavailable	/api/v1/cognify /api/v1/search	模型/向量数据库服务未启动	检查 LLM 和向量数据库状态，确保服务正常运行