用途
Neo4j 文档导入技能用于把 PDF、HTML、纯文本、Markdown 等非结构化或半结构化文档导入 Neo4j，构建为知识图谱。典型使用场景包括：把文档分块并存储为带嵌入向量的 :Chunk 节点；用 LLM 从文本中抽取实体与关系；以编程方式使用 SimpleKGPipeline（neo4j-graphrag）；使用 Neo4j LLM Graph Builder 无代码 Web UI；通过 apoc.load.json 加载半结构化 JSON；以及把 LangChain 或 LlamaIndex 的文档加载器接入 Neo4j。
该技能同时说明不适用的场景：结构化 CSV / 关系型数据应使用 neo4j-import-skill；导入后的 GraphRAG 检索属于 neo4j-graphrag-skill；向量索引创建属于 neo4j-vector-search-skill；Cypher 查询编写属于 neo4j-cypher-skill。
主要能力
方案选择上，无需代码、想要拖拽式体验时使用 LLM Graph Builder Web UI；编程式处理 PDF / 文本使用 SimpleKGPipeline（neo4j-graphrag）；JSON / REST API 响应使用 apoc.load.json 或 Python + UNWIND；技术栈已有 LangChain 时使用 Neo4jGraph + 文档加载器；已有 LlamaIndex 时使用 Neo4jQueryEngine / Neo4jVectorStore；只做分块、不做实体抽取时使用手动分块 + MERGE 模式。
安装命令包括：pip install neo4j-graphrag（含 SimpleKGPipeline）、pip install neo4j-graphrag[openai]、[anthropic]、[google]、[bedrock]（v1.15.0 起）、[ollama]、[mistralai]、[fuzzy-matching]，以及仅支持 Python ≤ 3.13 的 pip install neo4j-graphrag[nlp]（spaCy 实体解析器，3.14+ 不支持）。环境要求为 neo4j>=5.17.0（支持 driver 6.x）、Python>=3.10、Neo4j>=5.18.1（Aura>=5.18.0）。
技能给出图谱模式定义的三种选项：简单字符串列表（由 LLM 推断描述，适合原型）、丰富 GraphSchema（生产中抽取质量最佳）、从文本自动抽取（"EXTRACTED" 或 "FREE"，输出噪声较大）。文档说明 GraphSchema 自 ≥1.8.0 起，entities/relations/potential_schema 已弃用，应使用 schema=GraphSchema(...)；约束（v1.15.0+）支持 UNIQUENESS、KEY、EXISTENCE 类型。
使用方式
使用 SimpleKGPipeline 时，需先创建 Neo4j 驱动，再配置 LLM（OpenAILLM、AnthropicLLM、VertexAILLM、OllamaLLM、BedrockLLM 等，接口一致）与 embedder，然后构造 pipeline 并运行。运行方式包括从文件（file_path，自动分发到 PdfLoader 或 MarkdownLoader）、从原始文本（text=）以及批量遍历文件。文档说明 from_pdf=True 自 v1.15.0 起已弃用，应改用 from_file=True；document_metadata 字典会作为属性存储到 :Document 节点上。
分块默认使用 FixedSizeSplitter(chunk_size=300, chunk_overlap=50)。分块建议：密集技术文本 256–512 / 重叠 50–80；叙事或新闻 512–1024 / 80–128；法律与金融文档 256–384 / 40–64。规则是分块需同时适配 LLM 抽取上下文与嵌入模型限制，且 chunk_size 绝不应超过 2048。
实体消解提供三种解析器：SinglePropertyExactMatchResolver（最快、良好的基线）、FuzzyMatchResolver（Levenshtein 相似度，需要 rapidfuzz）、SpaCySemanticMatchResolver（余弦相似度，需要 neo4j-graphrag[nlp]）。建议在批量导入之后运行解析器，而非内联运行。
图谱结构上，流水线始终生成词法图层次：(:Document) -[:HAS_CHUNK]-> (:Chunk) -[:NEXT_CHUNK]-> (:Chunk)，并有 (:Chunk)-[:FROM_DOCUMENT]->(:Document) 反向指针；实体抽取会追加 (:Chunk)-[:MENTIONS]->(:Person/:Organization) 及实体之间的关系。文档还给出导入后的验证 Cypher 查询。
无代码路径为 LLM Graph Builder：托管地址 https://llm-graph-builder.neo4jlabs.com/ ；本地方式为克隆 https://github.com/neo4j-labs/llm-graph-builder ，配置 API Key 后执行 docker-compose up，访问 http://localhost:8080 。支持来源包括 PDF、纯文本、Markdown、图片、网页、YouTube 转录、S3/GCS 桶上传；LLM 提供商包括 OpenAI、Gemini、Claude、Llama3、Diffbot、Qwen。其局限是：对长篇英文文本效果最好，对表格数据效果差（应使用 neo4j-import-skill 处理 CSV/Excel），不抽取可视化图表。
半结构化 JSON 可使用 APOC，例如 apoc.load.json("https://example.com/articles.json") 配合 UNWIND 与 MERGE，并用 IN TRANSACTIONS OF 1000 ROWS 分批；本地文件需放在 $NEO4J_HOME/import/ 或配置 APOC 白名单。可通过 RETURN apoc.version() 确认 APOC 是否可用。
LangChain 集成方式为使用 Neo4jGraph、PyPDFLoader、RecursiveCharacterTextSplitter、OpenAIEmbeddings，并手动执行 MERGE :Document 与 CREATE :Chunk 的 Cypher；实体抽取可使用 LLMGraphTransformer。
导入前应先创建约束与索引，包括 Document、Chunk 的 id 唯一约束，实体 name 唯一约束，以及 :Chunk 嵌入向量索引；在索引状态全部为 ONLINE 之前不应开始导入。
限制与注意事项
文档列出常见错误及修复：LLM 抽取到模式外节点类型（模式过松或 EXTRACTED 模式）、MissingEmbedderError（未传 embedder，即使不做向量检索也必须传）、抽取到零实体（LLM 上下文溢出，需减小 chunk_size）、导入后出现重复实体节点（未运行实体消解）、apoc.load.json 权限被拒（未配置白名单）、分块在句中截断（approximate=False，应设为 True）、chunk_size 过大导致 LLM 超时、SpaCySemanticMatchResolver 在 Python 3.14 失败、neo4j-driver 包自 6.0 起弃用（应使用 neo4j 包）、v1.13.0 起 NodeType 无属性时出现 ValidationError、from_pdf 弃用警告，以及 model_params 中的 response_format 被忽略（流水线自 v1.14.0 起自动为 OpenAI/VertexAI 启用结构化输出）。此外提供了验证清单，包括约束 ONLINE、向量索引先建、chunk_size 与重叠比例、使用 Document→HAS_CHUNK→Chunk 模式、填充 document_metadata、批量导入后运行实体解析器、确认 APOC、API Key 放入 .env 并加入 .gitignore 等。
本技能要求的具体收费、价格与效果数据暂未提供。