Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

refactor(template): 重构模板加载和搜索接口

yifanfeng97b59b2c50bce8
diff --git a/examples/template_api_demo.py b/examples/template_api_demo.py
index c705711..d90d326 100644
--- a/examples/template_api_demo.py
+++ b/examples/template_api_demo.py
@@ -23,6 +23,8 @@ from langchain_openai import ChatOpenAI, OpenAIEmbeddings
INPUT_FILE = Path(__file__).parent.parent / "tests" / "test_data" / "templates" / "biography_scientist.md"
+name = "life_event_timeline"
+# name = "knowledge_graph"
def main():
print("=" * 60)
@@ -34,53 +36,49 @@ def main():
return
print(f"\n📄 输入文件: {INPUT_FILE.name}")
- print(f"🎯 使用模板: general/life_event_timeline")
+ print(f"🎯 使用模板: general/{name}")
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
embedder = OpenAIEmbeddings(model="text-embedding-3-small")
print("\n[1] Template.list() - 列出所有模板")
- names = Template.list()
- print(f"共 {len(names)} 个模板")
+ templates = Template.list()
+ print(f"共 {len(templates)} 个模板")
- print("\n[2] Template.list_domains() - 列出所有领域")
- domains = Template.list_domains()
- print(f"共 {len(domains)} 个领域: {domains}")
-
- print("\n[3] Template.get() - 获取配置")
- config = Template.get("general/life_event_timeline")
+ print("\n[2] Template.get() - 获取配置")
+ config = Template.get(f"general/{name}")
if config:
print(f"找到: {config.name}, type: {config.type}")
else:
print("未找到")
- print("\n[4] Template.search(type='list') - 按类型搜索")
- results = Template.search(type="list")
+ print("\n[3] Template.list(filter_by_type='list') - 按类型搜索")
+ results = Template.list(filter_by_type="list")
print(f"找到 {len(results)} 个 list 类型模板")
- print("\n[5] Template.create() - 通过文件路径创建实例")
+ print("\n[4] Template.create() - 通过文件路径创建实例")
template = Template.create(
- 'life_event_timeline',
+ name,
+ language="zh",
llm_client=llm,
embedder=embedder,
- language="zh",
)
print(f"创建成功: {type(template).__name__}")
- print("\n[6] 读取输入文件")
+ print("\n[5] 读取输入文件")
with open(INPUT_FILE, "r", encoding="utf-8") as f:
content = f.read()
print(f"读取成功,共 {len(content)} 字符")
- print("\n[7] template.feed_text() - 喂入文本")
+ print("\n[6] template.feed_text() - 喂入文本")
template.feed_text(content)
print("✅ 知识提取完成")
- print("\n[8] template.build_index() - 构建索引")
+ print("\n[7] template.build_index() - 构建索引")
template.build_index()
print("✅ 索引构建完成")
- print("\n[9] template.show() - 展示结果")
+ print("\n[8] template.show() - 展示结果")
template.show()
print("\n" + "=" * 60)
diff --git a/hyperextract/templates/presets/general/graph.yaml b/hyperextract/templates/presets/general/graph.yaml
new file mode 100644
index 0000000..c2c712e
--- /dev/null
+++ b/hyperextract/templates/presets/general/graph.yaml
@@ -0,0 +1,62 @@
+language: zh
+name: knowledge_graph
+type: graph
+tags: [general]
+description: '通用知识图谱 - 提取实体和它们之间的关系'
+
+output:
+ description: '通用知识图谱结构'
+ entities:
+ description: '提取的实体'
+ fields:
+ - name: name
+ type: str
+ description: '实体名称'
+ - name: type
+ type: str
+ description: '实体类型'
+ - name: description
+ type: str
+ description: '实体描述'
+ required: false
+ relations:
+ description: '实体之间的关系'
+ fields:
+ - name: source
+ type: str
+ description: '源实体'
+ - name: target
+ type: str
+ description: '目标实体'
+ - name: description
+ type: str
+ description: '关系描述'
+ required: false
+
+guideline:
+ target:
+ zh: '你是一位知识图谱专家,请从文本中提取实体和它们之间的关系。'
+ rules_for_entities:
+ zh:
+ - '提取所有相关实体'
+ - '为每个实体指定类型'
+ - '实体类型包括:人物、地点、组织、物品、概念、事件等'
+ rules_for_relations:
+ zh:
+ - '仅从提取的实体中创建关系边'
+ - '关系类型包括:包含、属于、相关、影响、合作、竞争等'
+ - 'source 和 target 都必须是已提取的实体'
+
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{target}'
+ relation_members:
+ source: source
+ target: target
+
+options:
+ extraction_mode: two_stage
+
+display:
+ entity_label: '{name} ({type})'
+ relation_label: '{description}'
diff --git a/hyperextract/types/graph.py b/hyperextract/types/graph.py
index 5fe0189..1dd6c7e 100644
--- a/hyperextract/types/graph.py
+++ b/hyperextract/types/graph.py
@@ -291,8 +291,8 @@ class AutoGraph(
)
# Store label extractors for visualization
- self.node_label_extractor = node_label_extractor
- self.edge_label_extractor = edge_label_extractor
+ self._node_label_extractor = node_label_extractor
+ self._edge_label_extractor = edge_label_extractor
# Call parent init
super().__init__(
diff --git a/hyperextract/types/hypergraph.py b/hyperextract/types/hypergraph.py
index 3f9ee00..d5c6987 100644
--- a/hyperextract/types/hypergraph.py
+++ b/hyperextract/types/hypergraph.py
@@ -296,8 +296,8 @@ class AutoHypergraph(
)
# Store label extractors for visualization
- self.node_label_extractor = node_label_extractor
- self.edge_label_extractor = edge_label_extractor
+ self._node_label_extractor = node_label_extractor
+ self._edge_label_extractor = edge_label_extractor
# Initialize Base Class
super().__init__(
diff --git a/hyperextract/utils/template_engine/factory.py b/hyperextract/utils/template_engine/factory.py
index c0e0f6b..de3da5d 100644
--- a/hyperextract/utils/template_engine/factory.py
+++ b/hyperextract/utils/template_engine/factory.py
@@ -328,9 +328,9 @@ class TemplateFactory:
def create(
cls,
source: Union[str, Path, TemplateCfg],
+ language: str,
llm_client: BaseChatModel,
embedder: Embeddings,
- language: str = "zh",
**kwargs,
):
"""Create template instance based on configuration.
@@ -340,9 +340,9 @@ class TemplateFactory:
- str: Template name (e.g., "knowledge_graph") or file path
- Path: YAML file path
- TemplateCfg: Template configuration instance
+ language: Language code for localization (e.g., 'zh', 'en') - required
llm_client: LLM client
embedder: Embedding model
- language: Language code for localization (e.g., 'zh', 'en')
**kwargs: Additional parameters to override config parameters
e.g., observation_time="2024-06-15", observation_location="Beijing"
@@ -351,23 +351,23 @@ class TemplateFactory:
Examples:
# By name (search via Gallery)
- template = TemplateFactory.create("knowledge_graph", llm, embedder)
+ template = TemplateFactory.create("knowledge_graph", "zh", llm, embedder)
# By file path
- template = TemplateFactory.create("/path/to/template.yaml", llm, embedder)
+ template = TemplateFactory.create("/path/to/template.yaml", "zh", llm, embedder)
# By TemplateCfg instance
- template = TemplateFactory.create(config, llm, embedder)
+ template = TemplateFactory.create(config, "zh", llm, embedder)
# For specific language
- template = TemplateFactory.create("knowledge_graph", llm, embedder, language="en")
+ template = TemplateFactory.create("knowledge_graph", "en", llm, embedder)
# For spatio-temporal templates, pass observation_time etc.
template = TemplateFactory.create(
"FinancialTemporalGraph",
+ "zh",
llm,
embedder,
- language="zh",
observation_time="2024-06-15",
observation_location="Beijing"
)
diff --git a/hyperextract/utils/template_engine/gallery.py b/hyperextract/utils/template_engine/gallery.py
index e0aa47d..4d827e7 100644
--- a/hyperextract/utils/template_engine/gallery.py
+++ b/hyperextract/utils/template_engine/gallery.py
@@ -4,7 +4,7 @@ Auto-loads templates from presets directory.
"""
from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Dict, Optional
from .parsers import TemplateCfg, load_template
@@ -18,14 +18,12 @@ class Gallery:
# Get template by path
config = Gallery.get("general/knowledge_graph")
- # List all templates
- print(Gallery.list())
+ # List all templates (returns Dict[str, TemplateCfg])
+ all_templates = Gallery.list()
- # List domains
- print(Gallery.list_domains())
-
- # Search templates
- results = Gallery.search(type="graph")
+ # List templates with filters
+ graph_templates = Gallery.list(filter_by_type="graph")
+ zh_templates = Gallery.list(filter_by_language="zh")
"""
_instance: Optional["Gallery"] = None
@@ -53,39 +51,30 @@ class Gallery:
return cls._instance._configs.get(f"general/{path}")
@classmethod
- def list(cls) -> List[str]:
- """List all available template names.
-
- Returns:
- List of template names
- """
- return list(cls._instance._configs.keys()) if cls._instance else []
-
- @classmethod
- def search(
+ def list(
cls,
- query: str = None,
- type: str = None,
- tag: str = None,
- language: str = None,
- ) -> List[TemplateCfg]:
- """Search templates by query, type, tag, or language.
+ filter_by_query: str = None,
+ filter_by_type: str = None,
+ filter_by_tag: str = None,
+ filter_by_language: str = None,
+ ) -> Dict[str, "TemplateCfg"]:
+ """List templates with optional filters.
Args:
- query: Search in template name/description
- type: Filter by autotype (e.g., "graph", "list", "model")
- tag: Filter by tag
- language: Filter by language (e.g., "zh", "en")
+ filter_by_query: Search in template name/description
+ filter_by_type: Filter by autotype (e.g., "graph", "list", "model")
+ filter_by_tag: Filter by tag
+ filter_by_language: Filter by language (e.g., "zh", "en")
Returns:
- List of matching TemplateCfg
+ Dict mapping template name to TemplateCfg
"""
if not cls._instance:
- return []
+ return {}
- results = []
- for config in cls._instance._configs.values():
- q = query.lower() if query else None
+ results = {}
+ for key, config in cls._instance._configs.items():
+ q = filter_by_query.lower() if filter_by_query else None
if q and q not in config.name.lower():
desc = config.description
@@ -96,36 +85,21 @@ class Gallery:
):
continue
- if type and config.type != type:
+ if filter_by_type and config.type != filter_by_type:
continue
- if tag and (not config.tags or tag not in config.tags):
+ if filter_by_tag and (not config.tags or filter_by_tag not in config.tags):
continue
- if language:
+ if filter_by_language:
config_lang = config.language
if isinstance(config_lang, list):
- if language not in config_lang:
+ if filter_by_language not in config_lang:
continue
- elif config_lang != language:
+ elif config_lang != filter_by_language:
continue
- results.append(config)
+ results[key] = config
return results
- @classmethod
- def list_domains(cls) -> List[str]:
- """List all available domains (folder names in presets).
-
- Returns:
- List of domain names
- """
- base_dir = Path(__file__).parent.parent.parent / "templates" / "presets"
- domains = []
- if base_dir.exists():
- for item in base_dir.iterdir():
- if item.is_dir() and not item.name.startswith("_"):
- domains.append(item.name)
- return sorted(domains)
-
def _load_config(self, file_path: Path, presets_dir: Path) -> None:
try:
config = load_template(file_path)
diff --git a/hyperextract/utils/template_engine/parsers/identifiers.py b/hyperextract/utils/template_engine/parsers/identifiers.py
index e732f03..ea4f9a1 100644
--- a/hyperextract/utils/template_engine/parsers/identifiers.py
+++ b/hyperextract/utils/template_engine/parsers/identifiers.py
@@ -43,9 +43,9 @@ def _extractor(field_or_template: str) -> Callable[[Any], str]:
def _members_extractor(
members: dict[str, str] | str | list[str],
) -> Callable[[Any], Tuple[str, ...]]:
- """Relation members extractor:
+ """Relation members extractor:
Graph: {source: 's', target: 't'} -> lambda x: (x.s, x.t)
- Hypergraph: 'members' -> lambda x: tuple(sorted(x.members)) or
+ Hypergraph: 'members' -> lambda x: tuple(sorted(x.members)) or
'members' -> lambda x: tuple(sorted(x.m) for m in x.members)
"""
# Handle Graph
@@ -54,8 +54,10 @@ def _members_extractor(
def extractor(item: Any) -> Tuple[str, str]:
return tuple(
sorted(
- str(getattr(item, "source")),
- str(getattr(item, "target")),
+ [
+ str(getattr(item, "source")),
+ str(getattr(item, "target")),
+ ]
)
)
@@ -120,7 +122,7 @@ def parse_identifiers(
if autotype in ("spatial_graph", "spatio_temporal_graph"):
location_extractor = _extractor(identifiers.location_field)
rets.append(location_extractor)
-
+
return tuple(rets)
return None
diff --git a/hyperextract/utils/template_engine/parsers/loader.py b/hyperextract/utils/template_engine/parsers/loader.py
index 1b76dd8..66df71e 100644
--- a/hyperextract/utils/template_engine/parsers/loader.py
+++ b/hyperextract/utils/template_engine/parsers/loader.py
@@ -38,7 +38,7 @@ class TemplateCfg(BaseModel):
def _localize_data(
- value: str | List[str] | Dict[str, str | List[str]] | None,
+ value: str | List[str] | Dict[str, str | List[str]],
language: str,
) -> str:
"""Get multilingual text value, supports list format
diff --git a/hyperextract/utils/template_engine/parsers/output.py b/hyperextract/utils/template_engine/parsers/output.py
index f2c5730..677612b 100644
--- a/hyperextract/utils/template_engine/parsers/output.py
+++ b/hyperextract/utils/template_engine/parsers/output.py
@@ -29,11 +29,14 @@ def build_naive_schema(
kwargs = {
"description": field.description,
}
- if field.required is not None:
- kwargs["required"] = field.required
if field.default is not None:
kwargs["default"] = field.default
- schema_fields[field.name] = (TYPE_MAPPING[field.type], Field(**kwargs))
+ elif field.required is False: # 非必填且无默认值时,设 default=None
+ kwargs["default"] = None
+ schema_fields[field.name] = (
+ TYPE_MAPPING[field.type],
+ Field(**kwargs),
+ )
return create_model(name, __doc__=description, **schema_fields)
diff --git a/hyperextract/utils/template_engine/template.py b/hyperextract/utils/template_engine/template.py
index 6ad692f..317228e 100644
--- a/hyperextract/utils/template_engine/template.py
+++ b/hyperextract/utils/template_engine/template.py
@@ -3,7 +3,7 @@
Provides a clean API for searching and creating knowledge extraction templates.
"""
-from typing import List, Optional
+from typing import Dict, Optional
from pathlib import Path
from langchain_core.language_models import BaseChatModel
@@ -26,33 +26,29 @@ class Template:
# Get template config by path
config = Template.get("general/knowledge_graph")
- # Search templates
- results = Template.search(type="graph")
- results = Template.search(tag="finance")
- results = Template.search(query="知识图谱")
+ # List all templates (returns Dict[str, TemplateCfg])
+ all_templates = Template.list()
- # List all templates
- names = Template.list()
-
- # List domains
- domains = Template.list_domains()
+ # List templates with filters
+ graph_templates = Template.list(filter_by_type="graph")
+ zh_templates = Template.list(filter_by_language="zh")
"""
@staticmethod
def create(
source: str | Path,
+ language: str,
llm_client: Optional[BaseChatModel] = None,
embedder: Optional[Embeddings] = None,
- language: str = "en",
**kwargs,
):
"""Create template instance.
Args:
source: Template path (e.g., "general/knowledge_graph") or file path
+ language: Language code (e.g., "zh", "en") - required
llm_client: LLM client (reads from global config if not provided)
embedder: Embedder client (reads from global config if not provided)
- language: Language code (e.g., "zh", "en")
**kwargs: Additional parameters
Returns:
@@ -60,14 +56,15 @@ class Template:
Examples:
# By path
- template = Template.create("general/knowledge_graph", llm, emb)
+ template = Template.create("general/knowledge_graph", "zh", llm, emb)
# By file path
- template = Template.create("/path/to/template.yaml", llm, emb)
+ template = Template.create("/path/to/template.yaml", "zh", llm, emb)
# For temporal/spatial templates
template = Template.create(
"finance/financial_data_temporal_graph",
+ "zh",
llm,
emb,
observation_time="2024-06-15"
@@ -82,7 +79,7 @@ class Template:
llm_client = llm_client or default_llm
embedder = embedder or default_emb
- return TemplateFactory.create(source, llm_client, embedder, language=language, **kwargs)
+ return TemplateFactory.create(source, language, llm_client, embedder, **kwargs)
@staticmethod
def get(path: str) -> Optional[TemplateCfg]:
@@ -97,44 +94,28 @@ class Template:
return Gallery.get(path)
@staticmethod
- def search(
- query: Optional[str] = None,
- type: Optional[str] = None,
- tag: Optional[str] = None,
- language: Optional[str] = None,
- ) -> List[TemplateCfg]:
- """Search templates by various criteria.
+ def list(
+ filter_by_query: Optional[str] = None,
+ filter_by_type: Optional[str] = None,
+ filter_by_tag: Optional[str] = None,
+ filter_by_language: Optional[str] = None,
+ ) -> Dict[str, TemplateCfg]:
+ """List templates with optional filters.
Args:
- query: Search in template name/description
- type: Filter by autotype (e.g., "graph", "list", "model")
- tag: Filter by tag (e.g., "finance", "medicine")
- language: Filter by language (e.g., "zh", "en")
+ filter_by_query: Search in template name/description
+ filter_by_type: Filter by autotype (e.g., "graph", "list", "model")
+ filter_by_tag: Filter by tag
+ filter_by_language: Filter by language (e.g., "zh", "en")
Returns:
- List of matching TemplateCfg objects
+ Dict mapping template name to TemplateCfg
"""
- return Gallery.search(
- query=query,
- type=type,
- tag=tag,
- language=language,
+ return Gallery.list(
+ filter_by_query=filter_by_query,
+ filter_by_type=filter_by_type,
+ filter_by_tag=filter_by_tag,
+ filter_by_language=filter_by_language,
)
- @staticmethod
- def list() -> List[str]:
- """List all available template names.
-
- Returns:
- List of template names
- """
- return Gallery.list()
- @staticmethod
- def list_domains() -> List[str]:
- """List all available domains (folder names in presets).
-
- Returns:
- List of domain names
- """
- return Gallery.list_domains()