diff --git a/examples/README.md b/examples/README.md index a32b443..a2d9134 100644 --- a/examples/README.md +++ b/examples/README.md @@ -2,16 +2,25 @@ 示例按依赖复杂度分为三组，建议按顺序探索。 +**依赖标记说明：** + +| 标记 | 含义 | +|---|---| +| `零依赖` | 仅需项目本身，无需外部服务 | +| `需 LLM API` | 需要配置 LLM API 密钥（如 OpenAI） | +| `需 OceanBase` | 需要 OceanBase >= 4.2.2 或 seekdb | +| `需可选依赖` | 需要安装可选依赖（如 langchain、powermem） | + ## [basic/](basic/) — 入门示例 依赖最小，适合初次了解 ContextSeek。 -| 文件 | 后端 | 说明 | +| 文件 | 依赖 | 说明 | |---|---|---| -| `pipeline_file.py` | FileBackend（无需外部服务） | 本地文件后端，关键词检索 | -| `pipeline_ob.py` | OceanBase | 向量 + 全文混合检索 | -| `langchain.py` | FileBackend | LangChain Memory / Retriever 桥接 | -| `langchain_deepagents_example.py` | FileBackend（无需外部服务） | LangChain + DeepAgents + ContextSeek 的真实集成示例 | +| `pipeline_file.py` | `零依赖` | 本地文件后端，关键词检索 | +| `pipeline_ob.py` | `需 OceanBase` | 向量 + 全文混合检索 | +| `langchain.py` | `需可选依赖` | LangChain Memory / Retriever 桥接 | +| `langchain_deepagents_example.py` | `需 LLM API` | LangChain + DeepAgents + ContextSeek 的真实集成示例 | ```bash uv run python examples/basic/pipeline_file.py # 零外部依赖，推荐首选 @@ -23,11 +32,12 @@ uv run python examples/basic/pipeline_file.py # 零外部依赖，推荐首选 | 文件 | 依赖 | 说明 | |---|---|---| -| `research_agent.py` | 仅项目本身 | 所有核心功能综合演示（推荐） | -| `evidence_chain.py` | 仅项目本身 | 证据链溯源：`upstream` / `evidence_chain` / `chain_confidence` | -| `llm_full_pipeline_ob.py` | OB + LLM API | Phase 1/2/3 完整 LLM 流水线 | -| `powermem_minimal.py` | 仅项目本身 | PowerMem 最小集成路径（~50 行） | -| `powermem_plug.py` | 可选 powermem | PowerMem DataPlug 完整演示 | +| `research_agent.py` | `零依赖` | 所有核心功能综合演示（推荐） | +| `evidence_chain.py` | `零依赖` | 证据链溯源：`upstream` / `evidence_chain` / `chain_confidence` | +| `self_evolution_demo.py` | `零依赖` | 自演进四项特性：冲突检测、双时态、utility 反馈、pitfall 反思 | +| `llm_full_pipeline_ob.py` | `需 OceanBase` + `需 LLM API` | Phase 1/2/3 完整 LLM 流水线 | +| `powermem_minimal.py` | `零依赖` | PowerMem 最小集成路径（~50 行） | +| `powermem_plug.py` | `需可选依赖` | PowerMem DataPlug 完整演示 | ```bash uv run python examples/advanced/research_agent.py # 推荐：零外部依赖的完整演示 @@ -37,11 +47,13 @@ uv run python examples/advanced/research_agent.py # 推荐：零外部依赖的 需要 OceanBase >= 4.2.2（或 seekdb）且 `GEO_ENABLED=true`。 -| 文件 | 场景 | -|---|---| -| `poi_search.py` | 地图 POI 关键词 + 地理混合搜索 | -| `ride_hailing.py` | 打车调度：司机 / 订单 / 热力区域 | -| `autonomous_driving.py` | 智能驾驶：HD 地图 / ODD / 道路事件 | +| 文件 | 依赖 | 场景 | +|---|---|---| +| `poi_search.py` | `需 OceanBase` | 地图 POI 关键词 + 地理混合搜索 | +| `ride_hailing.py` | `需 OceanBase` | 打车调度：司机 / 订单 / 热力区域 | +| `autonomous_driving.py` | `需 OceanBase` | 智能驾驶：HD 地图 / ODD / 道路事件 | +| `gis_memory.py` | `需 OceanBase` | GPS 轨迹 → 地点事实 → 行为知识 | +| `smart_swap.py` | `需 OceanBase` | GIS 记忆驱动的分层换电推荐 | ```bash GEO_ENABLED=true uv run python examples/gis/poi_search.py diff --git a/examples/advanced/README.md b/examples/advanced/README.md index 2f96b74..32edbd9 100644 --- a/examples/advanced/README.md +++ b/examples/advanced/README.md @@ -2,7 +2,9 @@ 完整能力展示，涵盖 LLM 集成、演进流水线和 DataPlug 扩展。 -## research_agent.py — 综合功能演示（推荐新用户看完 basic 后从这里开始） +> 依赖标记说明见 [examples/README.md](../README.md#依赖标记说明)。 + +## research_agent.py — 综合功能演示（推荐新用户看完 basic 后从这里开始） `零依赖` ```bash uv run python examples/advanced/research_agent.py @@ -25,7 +27,7 @@ uv run python examples/advanced/research_agent.py --- -## evidence_chain.py — 证据链与溯源 API 演示 +## evidence_chain.py — 证据链与溯源 API 演示 `零依赖` ```bash uv run python examples/advanced/evidence_chain.py @@ -43,7 +45,7 @@ uv run python examples/advanced/evidence_chain.py --- -## llm_full_pipeline_ob.py — 真实 LLM + OceanBase 完整流水线 +## llm_full_pipeline_ob.py — 真实 LLM + OceanBase 完整流水线 `需 OceanBase` `需 LLM API` ```bash uv run python examples/advanced/llm_full_pipeline_ob.py @@ -63,7 +65,7 @@ pip install "contextseek[oceanbase,langchain,openai]" --- -## powermem_minimal.py — PowerMem 最小集成路径 +## powermem_minimal.py — PowerMem 最小集成路径 `零依赖` ```bash uv run python examples/advanced/powermem_minimal.py @@ -76,7 +78,7 @@ uv run python examples/advanced/powermem_minimal.py --- -## powermem_plug.py — PowerMem DataPlug 完整演示 +## powermem_plug.py — PowerMem DataPlug 完整演示 `需可选依赖` ```bash uv run python examples/advanced/powermem_plug.py diff --git a/examples/basic/README.md b/examples/basic/README.md index e77a15e..9b4e58c 100644 --- a/examples/basic/README.md +++ b/examples/basic/README.md @@ -2,7 +2,9 @@ 入门示例，依赖最小，适合初次了解 ContextSeek 的用户。 -## pipeline_file.py — FileBackend 本地文件后端 +> 依赖标记说明见 [examples/README.md](../README.md#依赖标记说明)。 + +## pipeline_file.py — FileBackend 本地文件后端 `零依赖` ```bash uv run python examples/basic/pipeline_file.py @@ -19,7 +21,7 @@ uv run python examples/basic/pipeline_file.py --- -## pipeline_ob.py — OceanBase 后端 + 语义检索 +## pipeline_ob.py — OceanBase 后端 + 语义检索 `需 OceanBase` ```bash uv run python examples/basic/pipeline_ob.py @@ -43,7 +45,7 @@ pip install "contextseek[dashscope]" # 阿里云百炼 / DashScope --- -## langchain.py — LangChain 桥接层 +## langchain.py — LangChain 桥接层 `需可选依赖` ```bash uv run python examples/basic/langchain.py @@ -62,7 +64,7 @@ pip install "contextseek[langchain]" --- -## langchain_deepagents_example.py — LangChain + DeepAgents 集成示例 +## langchain_deepagents_example.py — LangChain + DeepAgents 集成示例 `需 LLM API` ```bash uv run python examples/basic/langchain_deepagents_example.py diff --git a/examples/gis/README.md b/examples/gis/README.md index 207f6bb..b0dede4 100644 --- a/examples/gis/README.md +++ b/examples/gis/README.md @@ -2,6 +2,9 @@ 地理空间场景示例，展示 ContextSeek 在位置感知应用中的能力。 +> 依赖标记说明见 [examples/README.md](../README.md#依赖标记说明)。 +> 本目录所有示例均为 `需 OceanBase`。 + ## 运行前提（所有示例通用） - OceanBase >= 4.2.2 或 seekdb @@ -43,7 +46,7 @@ export OB_DB_NAME=contextseek --- -## poi_search.py — 地图 POI 搜索 +## poi_search.py — 地图 POI 搜索 `需 OceanBase` ```bash uv run python examples/gis/poi_search.py @@ -57,7 +60,7 @@ uv run python examples/gis/poi_search.py --- -## ride_hailing.py — 打车调度场景 +## ride_hailing.py — 打车调度场景 `需 OceanBase` ```bash uv run python examples/gis/ride_hailing.py @@ -71,7 +74,7 @@ uv run python examples/gis/ride_hailing.py --- -## autonomous_driving.py — 智能驾驶场景 +## autonomous_driving.py — 智能驾驶场景 `需 OceanBase` ```bash uv run python examples/gis/autonomous_driving.py @@ -87,7 +90,7 @@ uv run python examples/gis/autonomous_driving.py --- -## gis_memory.py — GIS 记忆生成（运行 smart_swap.py 前必跑） +## gis_memory.py — GIS 记忆生成（运行 smart_swap.py 前必跑） `需 OceanBase` ```bash uv run python examples/gis/gis_memory.py @@ -104,7 +107,7 @@ uv run python examples/gis/gis_memory.py --- -## smart_swap.py — GIS 记忆驱动的智能换电推荐 +## smart_swap.py — GIS 记忆驱动的智能换电推荐 `需 OceanBase` > **前提：先运行 `gis_memory.py`**，否则场景 1/2 降级为常规推荐