如何用 Pydantic AI 构建 Typed Agentic RAG 让 RAG 回答带可逐字核对的引用并在证据不足时拒绝回答【免费下载链接】awesome-llm-apps100 AI Agents, Agent Skills and RAG Apps - Free and Open Source.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-llm-apps本文以 awesome-llm-apps 仓库中的 agentic_typed_rag_pydanticai 为例完成一个具体任务把一个基于 Pydantic AI 的 Typed Agentic RAG 应用跑起来并验证它的两个核心行为——每条回答都附带能逐字核对的引用source、chunk_id、原文片段以及在检索证据不足时直接拒绝回答而不是让模型猜。该应用是一个 Streamlit 界面回答内容来自你上传的 PDF 或一个文档 URL向量库是会话级的 NumPy 内存索引不需要任何数据库服务。运行前提来自项目 READMEPython 3.12 或更高版本一个 OpenAI API key 或一个 Anthropic API key。安装依赖在仓库根目录执行以下命令README 给出的原始步骤cd rag_tutorials/agentic_typed_rag_pydanticai python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .envrequirements.txt 固定了依赖版本包括pydantic-ai2.10.0、streamlit1.59.2、openai2.45.0、anthropic0.116.0、pypdf6.14.2、numpy2.5.1、python-dotenv1.2.2。然后编辑.env填入其中一个 key.env.example 中还有可选的RAG_MODEL覆盖项OPENAI_API_KEYyour-key或ANTHROPIC_API_KEYyour-key这里your-key是你必须替换的值对应你向 OpenAI 或 Anthropic 申请的密钥。启动应用在rag_tutorials/agentic_typed_rag_pydanticai目录下启动streamlit run app.py启动后 app.py 会在侧边栏显示当前配置状态选中的 answer providerOpenAI 或 Anthropic、对应的 key 是否已加载未加载会显示Set {key_name} in .env before asking a question.的警告、当前模型名以及两个可调项EmbeddingsAuto、OpenAI、Local hashing三档。Auto 模式下如果设置了OPENAI_API_KEY就用 Pydantic AI 的 OpenAIEmbeddertext-embedding-3-small只有ANTHROPIC_API_KEY时用本地 hashing 后端因为 Anthropic 没有 embeddings API。README 的说明是本地后端适合关键词导向的演示要跨同义改写的语义检索应选 OpenAI embeddings。Refusal threshold滑杆范围 0.05–0.60默认 0.20。低于该检索分的问题会在 LLM 调用之前被拒绝。默认的 answer 模型是openai:gpt-5.2和anthropic:claude-sonnet-4-6见 agent.py 的DEFAULT_MODELS。改模型有两种方式修改侧边栏的 model 输入框或设置环境变量RAG_MODEL为任意 Pydantic AI 模型字符串例如RAG_MODELopenai:gpt-5.2。模型解析优先级在resolve_model_name()中实现RAG_MODEL优先其次按 key 决定默认值两个 key 都没有时会抛出Set OPENAI_API_KEY or ANTHROPIC_API_KEY before asking a question。三层机制引用怎么核对、拒绝怎么触发在看界面结果之前先弄清楚 agent.py 里的判定逻辑验证时才有对照标准。1. 类型化输出约束。应用的最终输出不是自由文本而是 Pydantic 模型Answertext、citationslist[Citation]、confidence0 到 1、answered。模型级校验器强制两条规则answeredTrue时至少要有 1 条 citationansweredFalse时不允许携带 citation。每条Citation包含source、chunk_id、quoted_span三个字段且都不允许为空白。2. 检索预检门槛deterministic refusal gate。answer_question()会先调用retrieve_evidence()做一次预检取检索结果中最高余弦分top_score与min_relevance默认 0.2即DEFAULT_MIN_RELEVANCE比较。enough_evidence为False时直接返回Answer.insufficient_evidence(top_score)此时answeredFalse、citations 为空不会发起任何 LLM 请求。3. 模型输出后的逐字引用复核。即使模型给出了answeredTrue的输出validate_grounded_answer()仍会做两次拦截消息中没有出现过retrieve工具调用_used_retrieve检查的直接转为拒绝每条 citation 用source chunk_id到向量库回查 chunkquoted_span经归一化压缩空白、转小写后必须是该 chunk 文本的逐字子串且长度不小于 8 个字符。任何一条 citation 无效或缺失整个回答都会变成拒绝。拒绝时展示的固定文案REFUSAL_TEXT是I do not have enough evidence in the indexed sources to answer that question.检索本身由 rag.py 负责PDF 按页抽取文本pypdf或抓取 URL 文本切成 180 词窗口、30 词重叠的 chunkDEFAULT_CHUNK_SIZE/DEFAULT_CHUNK_OVERLAPchunk_id 形如policy.pdf:p1:c1来源:页码:c序号嵌入后存入会话级InMemoryVectorStore检索默认取 top 4分数裁剪到 0–1。在界面上验证两种结果按 README 的操作路径上传一个或多个 PDF可选地填入一个文档 URL点Build knowledge base。构建成功后Index status 区会以{source}: {chunks} chunks逐行列出索引来源侧边栏出现 Indexed chunks 指标。问一个语料内的问题回答区显示答案正文、一条置信度进度条Answer confidence: …以及Citations区——每条引用是一个折叠面板标题为{source} | {chunk_id}展开后以代码块展示quoted_span。你可以拿这个片段回到原文逐字比对这正是可逐字核对的落点。问一个与语料无关的问题README 的建议界面显示一个红色警告框内容就是上面的REFUSAL_TEXT下方进度条标注Best retrieval similarity: …。这条路径下没有消耗任何 LLM 调用。注意两条前置校验构建时若 PDF 抽不出文本会报No extractable text found in {source}未设置对应 key 就提问会显示Set {key_name} before asking a question.。文档 URL 只支持公开的 http/https 页面、text/html或text/plain类型、正文不超过 2 MBlocalhost、私网地址会被拒绝validate_public_url抛出Private or local URLs are not supported。用确定性测试套件复核行为不想消耗 API 额度时用项目自带的测试套件。README 说明该套件使用 Pydantic AI 的TestModel不发起任何 provider 请求python3 test_typed_rag.pytest_typed_rag.py 覆盖的关键断言数值均为测试用例数据不是运行时固定预期test_out_of_corpus_question_refuses_without_model_request把models.ALLOW_MODEL_REQUESTS置为False后提问语料外问题断言answeredFalse、citations 为空、文本含 enough evidence——证明拒绝确实发生在模型调用之前test_forged_citation_forces_refusal测试文档写的是 seventy dollars per day而TestModel伪造的引用是 one hundred dollars per day断言最终answeredFalse且 citations 为空——证明逐字复核会拦截伪造引用test_agent_calls_retrieve_and_returns_typed_cited_answer断言retrieve出现在工具调用列表中且引用被保留test_answer_model_requires_citations_when_answeredansweredTrue但无 citation或confidence1.2越界都会触发 PydanticValidationErrortest_private_docs_urls_are_rejectedlocalhost、127.0.0.1、10.0.0.4等地址全部触发ValueError。测试全部通过加上界面里有引用的回答 红色警告的拒绝这两个可观察结果就是该应用两种核心行为被验证完成的标志。可调项与已知边界拒绝阈值侧边栏滑杆 0.05–0.60默认 0.20代码层默认值同为 0.2。top_k在 app.py 中固定为 4未暴露为界面配置。向量库生命周期内存中的会话级索引没有持久化。侧边栏的Clear knowledge base按钮会清空 store、索引来源和问答历史需要重新 Build。embedding 后端的取舍本地 hashing 后端默认 768 维local-hashing-*面向关键词匹配换用 OpenAI embeddings 才能覆盖同义改写检索。同一索引内不允许混合不同维度的向量embedding dimensions changed within one index。PDF 与 URL 的摄入限制PDF 无文本层时构建失败URL 有 15 秒超时、2 MB 上限和公网地址校验。以上限制都来自代码与 README 的原文描述未设置额外默认值。完成界面验证与python3 test_typed_rag.py全绿后这套类型化输出 检索预检 逐字引用复核的约束路径即可以 agent.py 和 rag.py 为参照直接复用。【免费下载链接】awesome-llm-apps100 AI Agents, Agent Skills and RAG Apps - Free and Open Source.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-llm-apps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
