semantica

在启动 Explorer 之前，请将 ALLOWED_ORIGINS（或 EXPLORER_CORS_ORIGINS）设置为包含确切的浏览器源。默认情况下，仅允许 http://localhost:5173 和 http://127.0.0.1:5173，并且同一允许列表同时控制着 /ws/graph-updates 的 WebSocket 握手。

对于端口 8020，运行：

ALLOWED_ORIGINS="http://127.0.0.1:8020,http://localhost:8020" \
semantica-explorer --graph any_graph.json --port 8020

然后打开 http://127.0.0.1:8020，并在修改该变量后重启服务器。此问题在 Semantica 0.6.7 中被观察到。

安装可选依赖，或在 slim-core 环境中跳过 Node2Vec 测试。

如需完整的测试环境：

pip install -e ".[dev,graph-embeddings]"

这会安装 gensim>=4.4.0。安装后，所有受影响的 Node2Vec 测试都应通过。

如果是有意不安装 gensim，请在每个受影响的测试模块顶部添加以下保护语句：

pytest.importorskip("gensim")  # Node2Vec requires semantica[graph-embeddings]

将其应用于以下文件中的八个测试：
- tests/context/test_banking_context_graphs_e2e.py
- tests/context/test_context_explainability_regression.py
- tests/kg/test_enhanced_algorithms_e2e.py
- tests/kg/test_provenance_integration.py
- tests/test_030_realworld_comprehensive.py
- tests/vector_store/test_decision_embedding_pipeline.py

不要将 gensim 检查从 NodeEmbedder.__init__ 移到 _train_word2vec() 中：slim-core 契约有意依赖构造函数抛出异常，以便调用方能够优雅地禁用 Node2Vec。依赖此行为的测试为 test_node_embedder_gensim_missing_hint、test_agent_context_with_graph_builds_without_gensim 和 test_graph_components_without_gensim_keep_everything_but_node2vec。

在你的 virtualenv 中安装可选依赖：

pip install -e ".[graph-embeddings]"

或者，对于已发布的软件包：

pip install "semantica[graph-embeddings]"

然后重新运行：

python -m pytest tests/kg/test_node_embeddings.py -q

对于仓库测试的修复，不要添加模块级的 pytest.importorskip("gensim")，因为 test_init_gensim_unavailable 和 test_init_invalid_method 必须在没有 gensim 的情况下运行。正确做法如下：

1. 在 pyproject.toml 中注册一个 marker：

[tool.pytest.ini_options]
markers = [
    "no_gensim: test runs without the optional gensim dependency"
]

2. 添加一个 autouse fixture，用于跳过依赖 gensim 的测试，除非该测试被标记为 no_gensim：

import pytest
from semantica.kg.node_embeddings import GENSIM_AVAILABLE

@pytest.fixture(autouse=True)
def require_gensim(request):
    if not GENSIM_AVAILABLE and "no_gensim" not in request.keywords:
        pytest.skip("Install semantica[graph-embeddings] to run Node2Vec tests")

3. 使用 @pytest.mark.no_gensim 标记 test_init_gensim_unavailable 和 test_init_invalid_method。

未安装 gensim 时的预期结果：2 个通过，31 个跳过。安装 gensim 后：全部 33 个测试通过。

CSVExporter.export_relationships() 仅将 source/source_id 和 target/target_id 识别为端点字段名。后端格式的记录使用 start_node_id/end_node_id（Neo4j、FalkorDB、Neptune 以及重命名后的 AGE 边）或 start_id/end_id（原始 AGE），因此规范化路径会静默地写入空的端点列，且不产生任何错误或警告。修复方法/临时解决方案：

1. 修复（补丁）：在 semantica/export/csv_exporter.py 中（export_relationships 方法），在方法开头使用来自 semantica/export/endpoint_names.py 的 canonical_endpoints 对记录进行处理（该文件定义了 SOURCE_ENDPOINT_NAMES/TARGET_ENDPOINT_NAMES）——这与 Parquet 和 Arrow 导出器已经采用的做法相同。这会将所有后端的字段拼写映射为 source_id/target_id，同时保持 source/target 和 source_id/target_id 照常工作。

2. 临时解决方案（无需修改代码）：在导出前重命名字段：
record = {"id": "r1", "start_node_id": "alice", "end_node_id": "acme", "type": "WORKS_AT"}
record["source_id"], record["target_id"] = record.pop("start_node_id"), record.pop("end_node_id")
CSVExporter().export_relationships([record], "rel.csv")

3. 替代路径：export({"edges": [record]}) 会保留这些值，但会以原始列名（start_node_id/end_node_id）写入，而不进行规范化。Parquet 和 Arrow 导出器不受影响。

FileObject 实例会被静默跳过，因为 GraphBuilder._process_item() 无法识别它们；它期望接收文本字符串或诸如 {"text": ...} 的字典。作为临时解决方案，请在构建图谱之前先转换每个摄取的 FileObject：

docs = FileIngestor().ingest_directory("./docs/", recursive=True)
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(
    [{"text": d.text} for d in docs]
)

PR #1951 中的永久修复使 build() 直接从 FileObject.text 提取文本，并记录一条指明不受支持的源类型的警告，而不是将其静默跳过。请更新到包含 PR #1951 的发布版本，或者如果您是从 main 分支运行的，请应用该更改。