10.3 · 自定义实体类型与属性

自定义实体类型与属性

自定义实体类型与属性

本文档介绍了 Graphiti 的实体类型和边类型系统，这些系统支持从非结构化文本中进行结构化知识提取。自定义实体类型定义了用于分类提取实体的类别，而自定义属性则使用 Pydantic 模型定义了应为每个实体或关系提取的结构化字段。

目的与范围

Graphiti 的知识提取使用大语言模型（LLM）来识别文本中的实体和关系。默认情况下，所有实体都被归类为 Entity 类型，除了名称和摘要之外没有结构化属性。自定义实体类型系统允许用户：

1. 定义实体类别（例如，人物、组织、地点）以进行语义分类。graphiti_core/nodes.py:290-300
2. 提取结构化属性作为 Pydantic 字段（例如，age: int、occupation: str）。graphiti_core/nodes.py:301-302
3. 定义关系类型并附带自定义属性（例如，EMPLOYED_AT 带有 position）。graphiti_core/edges.py:31-47
4. 控制提取过程，通过排除通用类型或强制使用特定签名。graphiti_core/nodes.py:290-300

实体类型系统架构

下图连接了自然语言空间（用户定义）与代码实体空间（提取管线）。

实体提取与属性流程

Graphiti · 实体提取与属性流程 · 图 1

来源： graphiti_core/nodes.py:290-302、graphiti_core/prompts/extract_nodes.py:37-41

定义自定义实体类型

实体类型被定义为 Pydantic BaseModel 的子类。类的文档字符串至关重要，因为它充当了大语言模型的类型描述。graphiti_core/nodes.py:290-300

基本实体类型定义

from pydantic import BaseModel, Field

class Person(BaseModel):
    """对话或文档中提到的人物。"""
    age: int | None = Field(None, description="人物的年龄（以年为单位）")
    occupation: str | None = Field(None, description="人物的工作或职业")

来源： graphiti_core/nodes.py:290-300、graphiti_core/prompts/extract_nodes.py:38-40

实体类型上下文构建

函数 _build_entity_types_context 将这些模型映射到用于大语言模型提示的整数 ID。graphiti_core/nodes.py:290-300

自定义边类型与签名

边类型定义了关系模式。与实体不同，边通常需要一个签名（源类型、目标类型）才能在特定上下文中有效。graphiti_core/edges.py:31-47

边属性提取流程

Graphiti · 边属性提取流程 · 图 2

来源： graphiti_core/edges.py:31-47、graphiti_core/prompts/extract_edges.py:31-37

定义边属性

边的自定义属性在解析过程中使用 extract_attributes 提示版本来提取。graphiti_core/edges.py:31-47

class Employment(BaseModel):
    """人物与其雇主之间的关系。"""
    salary: int | None = Field(None, description="年薪")
    position: str | None = Field(None, description="职位名称")

校验与约束

Graphiti 会执行多项检查，以确保自定义模式不会与内部字段冲突。

1. 字段名称校验：validate_entity_types 确保自定义属性名称不与保留的 EntityNode 字段重叠（例如，uuid、name、group_id）。graphiti_core/utils/ontology_utils/entity_types_utils.py:23-37
2. Pydantic 强制校验：所有针对属性的 LLM 响应都会在节点处理期间通过 Pydantic 模型构造函数进行类型校验。graphiti_core/nodes.py:301-302
3. 排除机制：excluded_entity_types 列表允许用户阻止在偏好特定类型时创建通用的 Entity 节点。graphiti_core/nodes.py:290-300

提取提示与上下文

系统使用专门的提示来进行属性提取：

• 节点属性：prompt_library.extract_nodes.extract_attributes 使用 episode_content 和 entity_type 模式来填充字段。graphiti_core/prompts/extract_nodes.py:66-67
• 边属性：prompt_library.extract_edges.extract_attributes 使用关系 fact 和 reference_time 来解析时间或数值属性。graphiti_core/prompts/extract_edges.py:81-82

来源： graphiti_core/nodes.py:290-302、graphiti_core/edges.py:31-47、graphiti_core/utils/ontology_utils/entity_types_utils.py:23-37、graphiti_core/prompts/extract_nodes.py:66-67、graphiti_core/prompts/extract_edges.py:81-82