ag-ui-rag-agent基于 Pydantic AI 与 PostgreSQL PGVector 构建语义 混合搜索的 RAG 智能体【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents本文以 ag-ui-rag-agent/agent/README.md 中定义的 Semantic Search Agent 为核心完整讲解如何用 Pydantic AI 与 PostgreSQLPGVector 扩展搭建一个具备语义搜索与混合搜索双策略、可自动选择检索方式并总结结果的知识库问答智能体。读完后你可以掌握从建库、配置环境变量、文档摄取到 CLI 交互与 AG-UI 前端状态同步的完整实战链路。一、这个智能体解决了什么问题该智能体是一个智能知识库搜索系统官方定位为powered by Pydantic AI and PostgreSQL with PGVector。它提供两种检索能力并由 Agent 自动选择策略、对检索结果做总结Semantic Search语义搜索纯向量相似度检索基于 embeddingHybrid Search混合搜索语义向量与关键词匹配结合适合精确命中Intelligent Strategy SelectionAgent 根据查询类型自动选择检索方式Result Summarization从检索到的分块生成连贯的洞察性回答Interactive CLI基于 Rich 的交互式命令行支持实时流式输出Multi-Provider Support兼容任意 OpenAI 协议 APIOpenAI、Gemini、Ollama 等。从源码结构看该目录实际上处于两条形态的叠加状态README.md 描述的是独立的 Semantic Search Agent 形态而 agent.py 已升级为 AG-UIAgent User Interaction Protocol支持版本——检索结果会写入共享状态RAGState并通过状态快照事件推送给前端这一点本文会在第六节结合源码展开。二、前置条件与安装步骤README 给出的运行前提Python 3.10带 PGVector 扩展的 PostgreSQL一个 LLM API KeyOpenAI、Gemini、Ollama、Groq 或任意 OpenAI 兼容服务已建好、且包含 documents 与 chunks 数据的数据库仓库提供 schema。安装流程对应 README.md 的 Installation 一节进入 agent 目录安装依赖pip install -r requirements.txt初始化数据库 schema。仓库提供了现成的建库脚本 sql/schema.sqlREADME 给出两种执行方式在 Supabase/Postgres 平台里直接执行 SQL或用 psqlpsql -d your_database -f sql/schema.sql配置环境变量文件.envREADME 建议从.env.example复制后编辑该目录当前未包含此示例文件可参照下文配置项自行创建摄取文档。README 明确说明这一步必须先于运行 Agent 完成python -m ingestion.ingest --documents documents/仓库的 requirements.txt 也印证了技术栈核心为pydantic-ai[agui]、ag-ui、openai数据库层为asyncpg、psycopg2-binary、pgvectorWeb 层为fastapi、uvicorn、python-multipart数据与文档处理依赖pandas、numpy、scikit-learn、tiktoken、pypdf、python-docx、beautifulsoup4等开发工具为pytest、pytest-asyncio、black、ruff、mypy。三、配置体系环境变量与默认值README 列出的必需环境变量如下变量说明DATABASE_URL带 PGVector 的 PostgreSQL 连接串LLM_PROVIDER提供商名称openai、anthropic、ollama 等LLM_API_KEYLLM 提供商 API KeyLLM_MODEL使用的模型如 gpt-4.1-mini、gemini-2.5-flashLLM_BASE_URLAPI 基础地址默认https://api.openai.com/v1EMBEDDING_MODEL向量模型如 text-embedding-3-small、text-embedding-3-large这些变量在 settings.py 中通过pydantic_settings.BaseSettings统一解析load_settings()在缺少DATABASE_URL或 API Key 时会抛出带明确提示的错误。结合源码完整的配置项与默认值如下Settings类settings.py配置项默认值含义database_url必填PostgreSQL 连接 URLllm_provideropenaiLLM 提供商名称llm_api_key必填LLM API Keyllm_modelgpt-4o-mini检索与总结使用的对话模型llm_base_urlhttps://api.openai.com/v1OpenAI 兼容服务的 Base URLdefault_match_count10搜索默认返回条数max_match_count50允许的最大返回条数default_text_weight0.3混合搜索中关键词匹配权重0–1db_pool_min_size10连接池最小连接数db_pool_max_size20连接池最大连接数embedding_modeltext-embedding-3-small向量模型embedding_dimension1536向量维度多提供商支持的关键在于 providers.pyget_llm_model()用配置里的base_url与api_key构造OpenAIProvider再包一层OpenAIModel——因此只要把LLM_BASE_URL指向 Ollama、Groq 等 OpenAI 兼容端点即可切换模型get_model_info()则供info命令展示当前配置。四、数据库 Schema 与两个核心搜索函数README 的 Database Setup 一节概括了 schema 的四要素documents表存全文与元数据、chunks表存分块与向量、match_chunks()语义搜索函数、hybrid_search()混合搜索函数。sql/schema.sql 给出了完整实现4.1 表结构与索引documentsid UUID主键、title、source、content、metadata JSONB、时间戳字段并对metadata建 GIN 索引、对created_at建降序索引chunksid UUID主键、外键document_id级联删除、content、embedding vector(1536)、chunk_index、metadata JSONB、token_count关键索引包括idx_chunks_embeddingIVFFlat 余弦索引WITH (lists 1)、idx_chunks_document_id、以及供关键词路径使用的idx_chunks_content_trgmgin_trgm_ops三元组 GIN 索引。schema 同时启用vector、uuid-ossp、pg_trgm三个扩展并附有一个自动更新documents.updated_at的触发器update_documents_updated_at。4.2 match_chunks纯语义搜索函数签名match_chunks(query_embedding vector(1536), match_count INT DEFAULT 10)实现逻辑schema.sqlSELECT c.id AS chunk_id, c.document_id, c.content, 1 - (c.embedding query_embedding) AS similarity, -- 余弦距离转相似度 c.metadata, d.title AS document_title, d.source AS document_source FROM chunks c JOIN documents d ON c.document_id d.id WHERE c.embedding IS NOT NULL ORDER BY c.embedding query_embedding LIMIT match_count;要点用 PGVector 的余弦距离操作符排序并把相似度表达为1 - 距离因此返回值范围在 -1 到 1 之间、越接近 1 越相似。4.3 hybrid_search混合搜索函数签名hybrid_search(query_embedding vector(1536), query_text TEXT, match_count INT DEFAULT 10, text_weight FLOAT DEFAULT 0.3)。它用两个 CTE 分别产出向量路径结果vector_results同上按余弦距离取全部候选与文本路径结果text_results基于to_tsvector(english, ...)与plainto_tsquery做全文匹配、以ts_rank_cd计算文本分再做FULL OUTER JOIN合并公式为schema.sql(COALESCE(v.vector_sim, 0) * (1 - text_weight) COALESCE(t.text_sim, 0) * text_weight)::float8 AS combined_score即combined_score 向量相似度 × (1 − text_weight) 文本相似度 × text_weight按combined_score DESC取前match_count条并同时返回vector_similarity与text_similarity两个子分方便上层解释排序原因。默认text_weight 0.3意味着混合检索以语义为主、关键词为辅查专有名词时调高该权重可以让精确词命中占更大比重。此外 schema 还提供了get_document_chunks(doc_id)函数按chunk_index顺序返回某文档的全部分块用于从分块回溯全文结构的场景。五、两种搜索策略适用场景与工具层实现README 对策略选择给出了清晰的经验法则语义搜索Semantic Search适合概念性、主题性查询例如concepts similar to machine learningideas about artificial intelligencerelated to neural networks混合搜索Hybrid Search适合特定事实与技术术语例如OpenAI GPT-4 specificationsNASDAQ:NVDA stock pricespecific quote from Sam AltmanREADME 说明Agent 会根据查询自动选择合适的策略也可以在 prompt 中显式指定检索类型。工具层实现在 tools.py。semantic_search()与hybrid_search()两个协程的关键行为均以RunContext[AgentDependencies]注入依赖参数兜底与钳制match_count缺省时取settings.default_match_count10并统一min(match_count, max_match_count)上限 50text_weight缺省时优先读会话级user_preferences[text_weight]再落到settings.default_text_weight0.3且被钳制在[0.0, 1.0]查询向量化通过deps.get_embedding(query)生成查询向量——dependencies.py 中该函数调用 OpenAI 兼容 API 的embeddings.create(modelembedding_model, inputtext)并返回浮点列表向量字符串格式Python 侧手工拼成 PGVector 接受的[0.1,0.2,...]逗号后无空格格式再执行SELECT * FROM match_chunks($1::vector, $2)/SELECT * FROM hybrid_search($1::vector, $2, $3, $4)结果模型semantic_search返回SearchResult列表chunk_id、document_id、content、similarity、metadata、document_title、document_sourcehybrid_search返回附带combined_score、vector_similarity、text_similarity的字典列表错误处理数据库异常时打印并返回空列表保证 Agent 不会因检索失败而崩溃。tests/test_tools.py 用 mock 数据库验证了这些行为自定义match_count是否正确下传test_semantic_search_with_custom_count断言第 3 个参数为 5、超过上限时被钳制到max_match_count50、embedding 生成参数正确、空结果与异常路径等。六、AG-UI 形态共享状态与工具事件源码级补充在 agent.py 中Agent 已升级为 AG-UI 支持版本这是理解本目录名的关键共享状态RAGStateagent.py包含retrieved_chunksRetrievedChunk列表含 chunk_id、content、similarity、document_title、highlight 等字段、current_query、search_history只保留最近 10 条、selected_chunk_id、total_chunks_in_kb、knowledge_base_statusAgent 定义rag_agent Agent(get_llm_model(), deps_typeStateDeps[RAGState], system_promptMAIN_SYSTEM_PROMPT)工具集search_knowledge_base(query, match_count, search_type)执行语义或混合检索把结果写入state.retrieved_chunks并返回StateSnapshotEvent前端据此刷新列表出错时清空 chunks 并把knowledge_base_status置为error: ...clear_search_results()清空当前结果与选中项select_chunk(chunk_id)高亮指定分块get_knowledge_base_stats()执行SELECT COUNT(*) FROM chunks更新知识库统计display_search_results()发出名为DisplaySearchResults的CustomEvent携带 chunks、query、total_results 触发 UI 展示动态指令rag_agent.instructions装饰的rag_instructions每次运行时根据状态拼装系统指令——有检索结果时会把 Top 5 分块的得分、来源与前 200 字符摘要注入 prompt让模型基于真实检索内容作答应用导出文件末尾app rag_agent.to_ag_ui(depsStateDeps(RAGState()))__main__下用uvicorn在0.0.0.0:8000启动agent.py。仓库上层还有一个 Next.js/CopilotKit 前端见 README_AGUI_SETUP.md 与 src/app/api/copilotkit/route.ts与之对接。系统提示词基础版在 prompts.py要求仅在用户明确需要知识库信息时才搜索、问候语直接回复不触发检索、优先小match_count5–10聚焦结果并给出了text_weight的调节建议get_dynamic_prompt()还会把会话 ID、用户偏好search_type、text_weight、result_count与最近 3 次搜索历史拼入上下文。七、文档摄取管道Ingestion PipelineREADME 中必须先摄取文档一步的实现在 ingestion/ingest.py。完整支持的命令行参数argparse定义见 ingest.pypython -m ingestion.ingest \ --documents documents/ \ --chunk-size 1000 \ --chunk-overlap 200 \ --no-semantic \ --clean \ --verbose参数默认值说明--documents/-ddocuments文档目录递归查找*.md、*.markdown、*.txt--chunk-size1000目标分块字符数--chunk-overlap200分块重叠字符数--no-semantic关闭禁用语义分块改用纯规则分块--clean/-c关闭摄取前清空chunks与documents表--verbose/-v关闭日志级别提升至 DEBUG管道DocumentIngestionPipeline处理单个文档的流程读取文件UTF-8 失败回退 latin-1→ 从 Markdown 首行#提取标题否则用文件名→ 抽取元数据文件路径、大小、行数、词数若文档带 YAML frontmatter 则一并解析合并→ 分块 → 生成 embedding → 在单个事务中先插documents再逐条插chunksembedding 同样拼为[...]字符串写入vector列。结束后输出总结处理文档数、总分块数、错误数与总耗时。分块策略在 ingestion/chunker.pyChunkingConfig默认chunk_size1000、chunk_overlap200、max_chunk_size2000、min_chunk_size100并校验 overlap 必须小于 chunk size。SemanticChunker先按 Markdown 结构边界标题、段落、列表、代码块、表格切段再把段聚合到chunk_size以内超长段落会调用 LLM通过 Pydantic AI 临时 Agent以---CHUNK---分隔做语义切分失败时回退到句界优先的规则切分_simple_split在目标位置附近回溯.!?\n作为切点。SimpleChunker则完全按段落做规则分块、支持 overlap。仓库的 documents/ 目录自带 21 篇大科技 AI 行业 Markdown 样本如 doc1_openai_funding.md可直接用于端到端验证——这也解释了 README 中 NASDAQ:NVDA、Sam Altman 等示例查询的出处。八、交互式 CLI 使用README 给出的运行命令python -m cliCLI 提供的能力与命令表README.md 与 cli.py 的display_help一致命令作用help显示可用命令info展示系统配置LLM Provider/Model、Embedding Model、默认 match count 与 text weightclear清屏并重新显示欢迎面板set keyvalue设置会话偏好如set text_weight0.5自动尝试 int/float 转换exit/quit/q退出从 cli.py 源码看会话流程为main()初始化AgentDependencies建立 asyncpg 连接池、创建会话 UUID→ 循环读取输入 → 将最近 6 轮对话拼成 Previous conversation 上下文 → 通过search_agent.iter(prompt, depsdeps)流式执行逐节点处理模型请求节点中把PartDeltaEvent的content_delta实时打印为 Assistant 输出工具调用节点打印 Calling tool: ... 及参数预览长值截断、工具结果打印 ✅ Tool result: ...截断至 100 字符。set命令写入的user_preferences会被hybrid_search在计算text_weight时优先读取实现会话内在线调参。需注意当前 agent.py 导出的 Agent 实例名为rag_agentAG-UI 形态而 cli.py 与测试仍从模块导入search_agent从源码结构看CLI 入口与 Agent 模块之间尚存在命名未完全对齐的情况实际以仓库当前版本为准。九、测试与开发README 的 Development 一节给出的命令pytest tests/ black . ruff check .仓库 tests/ 目录包含test_agent.py、test_cli.py、test_dependencies.py、test_tools.py、test_integration.py、test_requirements.py等测试文件与共享 fixture 的conftest.py以及一份 VALIDATION_REPORT.md。以 test_tools.py 为例测试用AsyncMock模拟 asyncpg 连接覆盖基础检索、自定义条数、上限钳制、embedding 调用参数、数据库异常与空结果等路径是验证第五节所述工具行为的直接证据。README 描述的目录结构与实际文件一一对应semantic_search_agent/ ├── agent.py # 主 Agent 实现 ├── cli.py # 命令行界面 ├── dependencies.py # Agent 依赖 ├── providers.py # 模型提供商 ├── prompts.py # 系统提示词 ├── settings.py # 配置 ├── tools.py # 搜索工具 ├── ingestion/ # 文档摄取管道 ├── sql/ # 数据库 schema └── documents/ # 示例文档对应本仓库路径为 ag-ui-rag-agent/agent/其中ingestion/下另有embedder.pyembedding 客户端工厂、utils/下另有db_utils.py、models.pyIngestionConfig、IngestionResult等数据模型、providers.py。十、小结这套 Semantic Search Agent 的完整闭环是schema.sql用 PGVector 的余弦距离与 Postgres 全文检索实现match_chunks/hybrid_search两个数据库函数settings.py.env统一管理与 OpenAI 兼容端点的连接ingestion/管道负责把 Markdown 文档切成带 embedding 的分块入库tools.py把两个 SQL 函数包装为带参数钳制的 Pydantic AI 工具agent.py再将其扩展为 AG-UI 共享状态 Agent检索结果以状态快照事件驱动前端展示。配置时重点关注LLM_BASE_URL切换提供商、EMBEDDING_MODEL须与库内 1536 维向量匹配、default_text_weight混合检索的关键词占比三个参数即可在不同知识库场景下快速调整检索行为。【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ag-ui-rag-agent：基于 Pydantic AI 与 PostgreSQL PGVector 构建语义 + 混合搜索的 RAG 智能体
ag-ui-rag-agent基于 Pydantic AI 与 PostgreSQL PGVector 构建语义 混合搜索的 RAG 智能体【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents本文以 ag-ui-rag-agent/agent/README.md 中定义的 Semantic Search Agent 为核心完整讲解如何用 Pydantic AI 与 PostgreSQLPGVector 扩展搭建一个具备语义搜索与混合搜索双策略、可自动选择检索方式并总结结果的知识库问答智能体。读完后你可以掌握从建库、配置环境变量、文档摄取到 CLI 交互与 AG-UI 前端状态同步的完整实战链路。一、这个智能体解决了什么问题该智能体是一个智能知识库搜索系统官方定位为powered by Pydantic AI and PostgreSQL with PGVector。它提供两种检索能力并由 Agent 自动选择策略、对检索结果做总结Semantic Search语义搜索纯向量相似度检索基于 embeddingHybrid Search混合搜索语义向量与关键词匹配结合适合精确命中Intelligent Strategy SelectionAgent 根据查询类型自动选择检索方式Result Summarization从检索到的分块生成连贯的洞察性回答Interactive CLI基于 Rich 的交互式命令行支持实时流式输出Multi-Provider Support兼容任意 OpenAI 协议 APIOpenAI、Gemini、Ollama 等。从源码结构看该目录实际上处于两条形态的叠加状态README.md 描述的是独立的 Semantic Search Agent 形态而 agent.py 已升级为 AG-UIAgent User Interaction Protocol支持版本——检索结果会写入共享状态RAGState并通过状态快照事件推送给前端这一点本文会在第六节结合源码展开。二、前置条件与安装步骤README 给出的运行前提Python 3.10带 PGVector 扩展的 PostgreSQL一个 LLM API KeyOpenAI、Gemini、Ollama、Groq 或任意 OpenAI 兼容服务已建好、且包含 documents 与 chunks 数据的数据库仓库提供 schema。安装流程对应 README.md 的 Installation 一节进入 agent 目录安装依赖pip install -r requirements.txt初始化数据库 schema。仓库提供了现成的建库脚本 sql/schema.sqlREADME 给出两种执行方式在 Supabase/Postgres 平台里直接执行 SQL或用 psqlpsql -d your_database -f sql/schema.sql配置环境变量文件.envREADME 建议从.env.example复制后编辑该目录当前未包含此示例文件可参照下文配置项自行创建摄取文档。README 明确说明这一步必须先于运行 Agent 完成python -m ingestion.ingest --documents documents/仓库的 requirements.txt 也印证了技术栈核心为pydantic-ai[agui]、ag-ui、openai数据库层为asyncpg、psycopg2-binary、pgvectorWeb 层为fastapi、uvicorn、python-multipart数据与文档处理依赖pandas、numpy、scikit-learn、tiktoken、pypdf、python-docx、beautifulsoup4等开发工具为pytest、pytest-asyncio、black、ruff、mypy。三、配置体系环境变量与默认值README 列出的必需环境变量如下变量说明DATABASE_URL带 PGVector 的 PostgreSQL 连接串LLM_PROVIDER提供商名称openai、anthropic、ollama 等LLM_API_KEYLLM 提供商 API KeyLLM_MODEL使用的模型如 gpt-4.1-mini、gemini-2.5-flashLLM_BASE_URLAPI 基础地址默认https://api.openai.com/v1EMBEDDING_MODEL向量模型如 text-embedding-3-small、text-embedding-3-large这些变量在 settings.py 中通过pydantic_settings.BaseSettings统一解析load_settings()在缺少DATABASE_URL或 API Key 时会抛出带明确提示的错误。结合源码完整的配置项与默认值如下Settings类settings.py配置项默认值含义database_url必填PostgreSQL 连接 URLllm_provideropenaiLLM 提供商名称llm_api_key必填LLM API Keyllm_modelgpt-4o-mini检索与总结使用的对话模型llm_base_urlhttps://api.openai.com/v1OpenAI 兼容服务的 Base URLdefault_match_count10搜索默认返回条数max_match_count50允许的最大返回条数default_text_weight0.3混合搜索中关键词匹配权重0–1db_pool_min_size10连接池最小连接数db_pool_max_size20连接池最大连接数embedding_modeltext-embedding-3-small向量模型embedding_dimension1536向量维度多提供商支持的关键在于 providers.pyget_llm_model()用配置里的base_url与api_key构造OpenAIProvider再包一层OpenAIModel——因此只要把LLM_BASE_URL指向 Ollama、Groq 等 OpenAI 兼容端点即可切换模型get_model_info()则供info命令展示当前配置。四、数据库 Schema 与两个核心搜索函数README 的 Database Setup 一节概括了 schema 的四要素documents表存全文与元数据、chunks表存分块与向量、match_chunks()语义搜索函数、hybrid_search()混合搜索函数。sql/schema.sql 给出了完整实现4.1 表结构与索引documentsid UUID主键、title、source、content、metadata JSONB、时间戳字段并对metadata建 GIN 索引、对created_at建降序索引chunksid UUID主键、外键document_id级联删除、content、embedding vector(1536)、chunk_index、metadata JSONB、token_count关键索引包括idx_chunks_embeddingIVFFlat 余弦索引WITH (lists 1)、idx_chunks_document_id、以及供关键词路径使用的idx_chunks_content_trgmgin_trgm_ops三元组 GIN 索引。schema 同时启用vector、uuid-ossp、pg_trgm三个扩展并附有一个自动更新documents.updated_at的触发器update_documents_updated_at。4.2 match_chunks纯语义搜索函数签名match_chunks(query_embedding vector(1536), match_count INT DEFAULT 10)实现逻辑schema.sqlSELECT c.id AS chunk_id, c.document_id, c.content, 1 - (c.embedding query_embedding) AS similarity, -- 余弦距离转相似度 c.metadata, d.title AS document_title, d.source AS document_source FROM chunks c JOIN documents d ON c.document_id d.id WHERE c.embedding IS NOT NULL ORDER BY c.embedding query_embedding LIMIT match_count;要点用 PGVector 的余弦距离操作符排序并把相似度表达为1 - 距离因此返回值范围在 -1 到 1 之间、越接近 1 越相似。4.3 hybrid_search混合搜索函数签名hybrid_search(query_embedding vector(1536), query_text TEXT, match_count INT DEFAULT 10, text_weight FLOAT DEFAULT 0.3)。它用两个 CTE 分别产出向量路径结果vector_results同上按余弦距离取全部候选与文本路径结果text_results基于to_tsvector(english, ...)与plainto_tsquery做全文匹配、以ts_rank_cd计算文本分再做FULL OUTER JOIN合并公式为schema.sql(COALESCE(v.vector_sim, 0) * (1 - text_weight) COALESCE(t.text_sim, 0) * text_weight)::float8 AS combined_score即combined_score 向量相似度 × (1 − text_weight) 文本相似度 × text_weight按combined_score DESC取前match_count条并同时返回vector_similarity与text_similarity两个子分方便上层解释排序原因。默认text_weight 0.3意味着混合检索以语义为主、关键词为辅查专有名词时调高该权重可以让精确词命中占更大比重。此外 schema 还提供了get_document_chunks(doc_id)函数按chunk_index顺序返回某文档的全部分块用于从分块回溯全文结构的场景。五、两种搜索策略适用场景与工具层实现README 对策略选择给出了清晰的经验法则语义搜索Semantic Search适合概念性、主题性查询例如concepts similar to machine learningideas about artificial intelligencerelated to neural networks混合搜索Hybrid Search适合特定事实与技术术语例如OpenAI GPT-4 specificationsNASDAQ:NVDA stock pricespecific quote from Sam AltmanREADME 说明Agent 会根据查询自动选择合适的策略也可以在 prompt 中显式指定检索类型。工具层实现在 tools.py。semantic_search()与hybrid_search()两个协程的关键行为均以RunContext[AgentDependencies]注入依赖参数兜底与钳制match_count缺省时取settings.default_match_count10并统一min(match_count, max_match_count)上限 50text_weight缺省时优先读会话级user_preferences[text_weight]再落到settings.default_text_weight0.3且被钳制在[0.0, 1.0]查询向量化通过deps.get_embedding(query)生成查询向量——dependencies.py 中该函数调用 OpenAI 兼容 API 的embeddings.create(modelembedding_model, inputtext)并返回浮点列表向量字符串格式Python 侧手工拼成 PGVector 接受的[0.1,0.2,...]逗号后无空格格式再执行SELECT * FROM match_chunks($1::vector, $2)/SELECT * FROM hybrid_search($1::vector, $2, $3, $4)结果模型semantic_search返回SearchResult列表chunk_id、document_id、content、similarity、metadata、document_title、document_sourcehybrid_search返回附带combined_score、vector_similarity、text_similarity的字典列表错误处理数据库异常时打印并返回空列表保证 Agent 不会因检索失败而崩溃。tests/test_tools.py 用 mock 数据库验证了这些行为自定义match_count是否正确下传test_semantic_search_with_custom_count断言第 3 个参数为 5、超过上限时被钳制到max_match_count50、embedding 生成参数正确、空结果与异常路径等。六、AG-UI 形态共享状态与工具事件源码级补充在 agent.py 中Agent 已升级为 AG-UI 支持版本这是理解本目录名的关键共享状态RAGStateagent.py包含retrieved_chunksRetrievedChunk列表含 chunk_id、content、similarity、document_title、highlight 等字段、current_query、search_history只保留最近 10 条、selected_chunk_id、total_chunks_in_kb、knowledge_base_statusAgent 定义rag_agent Agent(get_llm_model(), deps_typeStateDeps[RAGState], system_promptMAIN_SYSTEM_PROMPT)工具集search_knowledge_base(query, match_count, search_type)执行语义或混合检索把结果写入state.retrieved_chunks并返回StateSnapshotEvent前端据此刷新列表出错时清空 chunks 并把knowledge_base_status置为error: ...clear_search_results()清空当前结果与选中项select_chunk(chunk_id)高亮指定分块get_knowledge_base_stats()执行SELECT COUNT(*) FROM chunks更新知识库统计display_search_results()发出名为DisplaySearchResults的CustomEvent携带 chunks、query、total_results 触发 UI 展示动态指令rag_agent.instructions装饰的rag_instructions每次运行时根据状态拼装系统指令——有检索结果时会把 Top 5 分块的得分、来源与前 200 字符摘要注入 prompt让模型基于真实检索内容作答应用导出文件末尾app rag_agent.to_ag_ui(depsStateDeps(RAGState()))__main__下用uvicorn在0.0.0.0:8000启动agent.py。仓库上层还有一个 Next.js/CopilotKit 前端见 README_AGUI_SETUP.md 与 src/app/api/copilotkit/route.ts与之对接。系统提示词基础版在 prompts.py要求仅在用户明确需要知识库信息时才搜索、问候语直接回复不触发检索、优先小match_count5–10聚焦结果并给出了text_weight的调节建议get_dynamic_prompt()还会把会话 ID、用户偏好search_type、text_weight、result_count与最近 3 次搜索历史拼入上下文。七、文档摄取管道Ingestion PipelineREADME 中必须先摄取文档一步的实现在 ingestion/ingest.py。完整支持的命令行参数argparse定义见 ingest.pypython -m ingestion.ingest \ --documents documents/ \ --chunk-size 1000 \ --chunk-overlap 200 \ --no-semantic \ --clean \ --verbose参数默认值说明--documents/-ddocuments文档目录递归查找*.md、*.markdown、*.txt--chunk-size1000目标分块字符数--chunk-overlap200分块重叠字符数--no-semantic关闭禁用语义分块改用纯规则分块--clean/-c关闭摄取前清空chunks与documents表--verbose/-v关闭日志级别提升至 DEBUG管道DocumentIngestionPipeline处理单个文档的流程读取文件UTF-8 失败回退 latin-1→ 从 Markdown 首行#提取标题否则用文件名→ 抽取元数据文件路径、大小、行数、词数若文档带 YAML frontmatter 则一并解析合并→ 分块 → 生成 embedding → 在单个事务中先插documents再逐条插chunksembedding 同样拼为[...]字符串写入vector列。结束后输出总结处理文档数、总分块数、错误数与总耗时。分块策略在 ingestion/chunker.pyChunkingConfig默认chunk_size1000、chunk_overlap200、max_chunk_size2000、min_chunk_size100并校验 overlap 必须小于 chunk size。SemanticChunker先按 Markdown 结构边界标题、段落、列表、代码块、表格切段再把段聚合到chunk_size以内超长段落会调用 LLM通过 Pydantic AI 临时 Agent以---CHUNK---分隔做语义切分失败时回退到句界优先的规则切分_simple_split在目标位置附近回溯.!?\n作为切点。SimpleChunker则完全按段落做规则分块、支持 overlap。仓库的 documents/ 目录自带 21 篇大科技 AI 行业 Markdown 样本如 doc1_openai_funding.md可直接用于端到端验证——这也解释了 README 中 NASDAQ:NVDA、Sam Altman 等示例查询的出处。八、交互式 CLI 使用README 给出的运行命令python -m cliCLI 提供的能力与命令表README.md 与 cli.py 的display_help一致命令作用help显示可用命令info展示系统配置LLM Provider/Model、Embedding Model、默认 match count 与 text weightclear清屏并重新显示欢迎面板set keyvalue设置会话偏好如set text_weight0.5自动尝试 int/float 转换exit/quit/q退出从 cli.py 源码看会话流程为main()初始化AgentDependencies建立 asyncpg 连接池、创建会话 UUID→ 循环读取输入 → 将最近 6 轮对话拼成 Previous conversation 上下文 → 通过search_agent.iter(prompt, depsdeps)流式执行逐节点处理模型请求节点中把PartDeltaEvent的content_delta实时打印为 Assistant 输出工具调用节点打印 Calling tool: ... 及参数预览长值截断、工具结果打印 ✅ Tool result: ...截断至 100 字符。set命令写入的user_preferences会被hybrid_search在计算text_weight时优先读取实现会话内在线调参。需注意当前 agent.py 导出的 Agent 实例名为rag_agentAG-UI 形态而 cli.py 与测试仍从模块导入search_agent从源码结构看CLI 入口与 Agent 模块之间尚存在命名未完全对齐的情况实际以仓库当前版本为准。九、测试与开发README 的 Development 一节给出的命令pytest tests/ black . ruff check .仓库 tests/ 目录包含test_agent.py、test_cli.py、test_dependencies.py、test_tools.py、test_integration.py、test_requirements.py等测试文件与共享 fixture 的conftest.py以及一份 VALIDATION_REPORT.md。以 test_tools.py 为例测试用AsyncMock模拟 asyncpg 连接覆盖基础检索、自定义条数、上限钳制、embedding 调用参数、数据库异常与空结果等路径是验证第五节所述工具行为的直接证据。README 描述的目录结构与实际文件一一对应semantic_search_agent/ ├── agent.py # 主 Agent 实现 ├── cli.py # 命令行界面 ├── dependencies.py # Agent 依赖 ├── providers.py # 模型提供商 ├── prompts.py # 系统提示词 ├── settings.py # 配置 ├── tools.py # 搜索工具 ├── ingestion/ # 文档摄取管道 ├── sql/ # 数据库 schema └── documents/ # 示例文档对应本仓库路径为 ag-ui-rag-agent/agent/其中ingestion/下另有embedder.pyembedding 客户端工厂、utils/下另有db_utils.py、models.pyIngestionConfig、IngestionResult等数据模型、providers.py。十、小结这套 Semantic Search Agent 的完整闭环是schema.sql用 PGVector 的余弦距离与 Postgres 全文检索实现match_chunks/hybrid_search两个数据库函数settings.py.env统一管理与 OpenAI 兼容端点的连接ingestion/管道负责把 Markdown 文档切成带 embedding 的分块入库tools.py把两个 SQL 函数包装为带参数钳制的 Pydantic AI 工具agent.py再将其扩展为 AG-UI 共享状态 Agent检索结果以状态快照事件驱动前端展示。配置时重点关注LLM_BASE_URL切换提供商、EMBEDDING_MODEL须与库内 1536 维向量匹配、default_text_weight混合检索的关键词占比三个参数即可在不同知识库场景下快速调整检索行为。【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考