10.3 · 自定义实体类型与 Attributes（Custom Entity Types and Attributes）

自定义实体类型与 Attributes（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/10.3-custom-entity-types-and-attributes

翻译时间：2026-05-27T08:44:46.633Z

翻译模型：deepseek-chat

原文字符数：7368

项目：Graphiti (graphiti)

---

自定义实体类型与属性

本文档介绍了 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

实体类型系统架构

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

实体提取与属性流程

graph TB
    subgraph "自然语言空间（用户定义）"
        A["Pydantic BaseModel<br/>'class Person(BaseModel)'"]
        B["字段定义<br/>'age: int'<br/>'occupation: str'"]
    end

    subgraph "代码实体空间（注册表与上下文）"
        C["'entity_types' 字典<br/>{'Person': Person}"]
        D["'_build_entity_types_context()'<br/>graphiti_core/nodes.py:290"]
    end

    subgraph "大语言模型执行空间"
        E["'extract_nodes()'<br/>graphiti_core/nodes.py:301"]
        F["'ExtractedEntities' 模式<br/>graphiti_core/prompts/extract_nodes.py:41"]
        G["'extract_attributes_from_nodes()'<br/>graphiti_core/nodes.py:301"]
    end

    subgraph "持久化"
        H["'EntityNode' 实例<br/>graphiti_core/nodes.py:250"]
        I["'node.attributes' 字典"]
    end

    A --> C
    B --> A
    C --> D
    D --> E
    E --> F
    F --> H
    H --> G
    G --> I

来源： 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

边属性提取流程

sequenceDiagram
    participant U as 用户代码
    participant E as "extract_edges()"
    participant R as "resolve_extracted_edge()"
    participant L as 大语言模型（提取属性）

    U->>E: 提供 'edge_types' 和 'edge_type_map'
    E->>E: 将 'relation_type' 匹配到 'edge_type_map'
    E->>R: 传递 'edge_type_candidates'
    R->>L: 使用 'edge_model' 生成响应
    L-->>R: 验证后的 JSON 属性
    R->>R: 更新 'resolved_edge.attributes'

来源： 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