agi-sample

agi-sample 是一个用于尝试 Python AI/LLM 新技术、新组件和新框架能力的 demo 仓库。它不是生产 SDK，而是用于快速验证 LangChain、LangGraph、AgentScope、RAG、文档智能、向量检索、本地模型和传统机器学习匹配等能力的样例集合。

本项目适合用于：

• 快速验证新的 LLM 框架、Agent 框架和工具调用模式；
• 沉淀 RAG、向量库、结构化输出、文档解析等实验代码；
• 对比云服务组件、本地模型组件和传统算法在业务场景中的可行性；
• 为后续正式项目提供最小可运行样例和实现参考。

本项目不适合直接作为生产工程使用。部分示例依赖本地文件、外部 API key 或实验性路径，运行前需要按 README 调整环境变量和输入文件。

.
├── README.md
├── requirements.txt
├── data/                         # 小型样例数据、FAISS 向量库样例、Flowgram 样例数据
├── docs/                         # PDF/压缩包/测试文档等输入资料
├── tests/                        # 结构整理与导入验证测试
└── src/agisample/
    ├── common/                   # 通用能力：连接、配置、路径等
    ├── langchain/                # LangChain 相关 demo
    │   ├── agents/               # Agent、Function Calling、工具调用
    │   ├── code/                 # 代码生成、代码评审等 LLM 编程样例
    │   ├── document/             # 文档/文件读取与 prompt 处理
    │   ├── extraction/           # 结构化输出、信息抽取、LangExtract
    │   ├── multimodal/           # 多模态/图像相关样例
    │   ├── rag/                  # RAG、重排序、问答链路
    │   ├── sql/                  # Text-to-SQL / Vanna 样例
    │   └── vectorstores/         # Embedding、FAISS、Elasticsearch 向量存储
    ├── langgraph/                # LangGraph 样例
    │   ├── basic/                # StateGraph 基础图、Flowgram 编译等入门样例
    │   ├── customersupport/      # 客服机器人：航班、酒店、租车等工具编排
    │   ├── hierarchical_teams/   # 分层多 Agent 团队（web/document 团队）
    │   └── a2a/                  # 双 Agent A2A 协议双向互调 demo
    ├── a2ui/                     # A2UI 销售查询：协议消息、数据绑定与交互回传
    ├── openui/                   # OpenUI Lang 销售查询：Vue 流式渲染、前端 Query 取数、$变量双向绑定
    ├── agentscope/               # AgentScope 框架样例
    ├── document_ai/              # 文档智能、OCR、发票/汇款/简历附件处理
    │   ├── azure_document_intelligence/
    │   └── resume_downloader/
    ├── local_models/             # 本地模型和 Gradio demo，例如 MiniCPM RAG
    ├── integrations/             # Langflow 等外部组件集成
    ├── machine_learning/         # 传统机器学习、匹配、降维等 demo
    ├── tools/                    # 通用工具脚本（组合查找、Markdown 恢复、邮件信息处理）
    ├── generic/                  # 旧路径兼容层
    └── base/                     # 旧路径兼容层

说明：原 framework/ 目录已按主题完成迁移并删除——图示例迁入 langgraph/（basic/、customersupport/、hierarchical_teams/），信息抽取迁入 langchain/extraction/，代码与文档处理迁入 langchain/code/、langchain/document/，传统 ML 迁入 machine_learning/，通用工具迁入 tools/。

入口：src/agisample/integrations/typesafe_jev_demo.py。 参考 官方 Quick start，一次请求同时演示：

• Choice：选择处理部门（billing、technical、sales），返回置信度及各选项概率。
• Score：依据三个等级评价不满程度，返回分数、评分标准和概率分布；分数可能为小数。
• Noul：判断紧迫性，返回 0～1 的数值，不应直接当作 Python 布尔值使用。

在仓库根目录运行（使用现有 .venv，无需重新创建）：

.\.venv\Scripts\python.exe -m pip install typesafe-sdk==0.7.1 python-dotenv==1.0.1
$env:TYPESAFE_API_KEY = "替换为你的 TypeSafe API 密钥"
.\.venv\Scripts\python.exe src\agisample\integrations\typesafe_jev_demo.py
.\.venv\Scripts\python.exe src\agisample\integrations\typesafe_jev_demo.py --text "我被重复扣款了，请协助退款。" --model jev-latest

也可在根目录 .env 中设置 TYPESAFE_API_KEY=你的密钥；已有环境变量优先。 密钥从 TypeSafe 控制台 获取。 程序输出中文摘要及完整 JSON（包含实际模型和 token 用量），结果以真实接口返回为准。 请求设置 30 秒 HTTP 超时，使用 SDK 默认重试策略，因此总耗时可能超过 30 秒。 输入或密钥缺失返回退出码 2，SDK/API 调用或响应异常返回 1，成功返回 0。

离线验证（模拟 HTTP 响应，不消耗 API 额度）：

.\.venv\Scripts\python.exe -m unittest discover -s tests -p test_typesafe_demo.py -v

建议使用 Python 3.11 或以上版本。

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

当前 requirements.txt 只覆盖了部分核心依赖。某些实验脚本还需要按需安装可选依赖，例如：

• Azure Document Intelligence：azure-ai-documentintelligence、azure-core
• 文档解析：pymupdf、pdfplumber、pymupdf4llm、markitdown
• 本地模型/前端：gradio、对应模型依赖
• 传统 ML：scikit-learn、torch、transformers
• LangChain v1 生态：langchain、langchain-openai、langchain-community、langchain-elasticsearch、langgraph、按需使用的 langchain-classic / langchain-experimental
• Agent 互调：a2a-sdk（已沉淀到 requirements.txt）
• 其他工具：agentscope、vanna、cohere

建议在运行具体 demo 前，根据 import 报错补充依赖，或把稳定需要的依赖逐步沉淀到 requirements.txt。

在项目根目录创建 .env 文件，按需配置以下变量。不要提交真实 token。

# OpenAI 兼容接口
OPENAI_API_KEY="sk-xxx"
OPENAI_BASE_URL="https://example.com/v1"

# AgentScope 示例
API_KEY="sk-xxx"

# Elasticsearch
ELASTICSEARCH_URL="http://localhost:9200"
ELASTICSEARCH_NAME="elastic"
ELASTICSEARCH_PASSWORD="password"

# Azure Document Intelligence
DI_KEY="your-document-intelligence-key"
DI_ENDPOINT="https://your-resource.cognitiveservices.azure.com/"

# Tavily / Web Search（LangGraph 多 Agent 示例按需使用）
TAVILY_API_KEY="tvly-xxx"

代码中通常通过以下方式加载：

from dotenv import load_dotenv, find_dotenv

_ = load_dotenv(find_dotenv())

运行前建议先设置 PYTHONPATH=src，确保源码包可被导入：

$env:PYTHONPATH='src'

$env:PYTHONPATH='src'; .\.venv\Scripts\python.exe tests/test_package_structure.py -q
$env:PYTHONPATH='src'; .\.venv\Scripts\python.exe -m compileall -q src/agisample

.\\.venv\\Scripts\\python.exe src/agisample/langchain/agents/sample_agent_process.py

.\\.venv\\Scripts\\python.exe src/agisample/langchain/rag/sample_rag_process.py

说明：RAG 示例依赖 docs/llama2.pdf 和 data/sample_db。如需重新构建向量库，可在代码中调用 SampleRagProcess().init_data()。

.\\.venv\\Scripts\\python.exe src/agisample/langgraph/basic/sample_graph_basic_chatbot.py

PYTHONPATH=src python src/agisample/document_ai/azure_document_intelligence/prebuilt_read.py
PYTHONPATH=src python src/agisample/document_ai/azure_document_intelligence/prebuilt_invoice.py

说明：这两个脚本需要配置 DI_KEY 和 DI_ENDPOINT，并根据本地实际文件路径调整输入文件。

PYTHONPATH=src python src/agisample/document_ai/resume_downloader/download_resume_file.py \
  --token "your-token" \
  --status "Submitted （Unread）" \
  --page-size 50 \
  --out downloads

• data/：保存样例 JSON、Flowgram 输入、FAISS 索引等小型数据。
• docs/：保存 PDF、压缩包、测试文档等输入资料。
• 各示例运行产生的 data_level0.bin、chroma.sqlite3 等属于向量库或 Chroma 生成产物，建议统一放到 data/ 或加入 .gitignore，避免源码目录混入运行时数据。
• downloads/ 已在 .gitignore 中，用于保存下载脚本输出。

新增 demo 时建议遵循以下规则：

1. 按主题选择目录：
   • LangChain 示例放到 agisample/langchain/；
   • LangGraph 示例放到 agisample/langgraph/；
   • 文档智能和文件解析放到 agisample/document_ai/；
   • 本地模型放到 agisample/local_models/；
   • 外部系统集成放到 agisample/integrations/；
   • 通用连接、路径、配置放到 agisample/common/。
2. 新文件优先使用 snake_case.py 命名。
3. 示例入口尽量提供 if __name__ == "__main__":，便于直接运行。
4. 不要在源码目录下写入大体积缓存、索引或下载文件。
5. 新增稳定依赖后同步更新 requirements.txt。
6. 涉及外部服务的 demo 不要提交真实凭证和公司内部数据。

原 framework/ 目录已完成迁移并删除，旧的 agisample.framework.* import 不再可用，请改用新路径，例如：

from agisample.langchain.rag.sample_rag_process import SampleRagProcess

generic/、base/ 目前仍保留为旧路径兼容层。后续当 README 和示例全部切换到新路径后，可以逐步删除 generic/、base/ 中的兼容 shim。

本轮已经完成 framework/ 全量迁移并删除该目录（图示例迁入 langgraph/，抽取/代码/文档处理迁入 langchain/，传统 ML 迁入 machine_learning/，通用工具迁入 tools/）。后续可以继续分阶段处理：

1. 增加统一路径工具，例如 agisample.common.paths.PROJECT_ROOT，替代各文件中不同层级的 Path(__file__).resolve().parents[...]。
2. 梳理 requirements.txt，把核心依赖和可选依赖拆分为 requirements.txt / requirements-dev.txt / requirements-optional.txt。
3. 为关键 demo 增加 smoke test，避免迁移后导入路径和入口脚本失效。

Function Calling 是增强 LLM 交互能力的重要技术。模型可以在对话中调用特定函数，以执行任务或获取外部数据。为了提升稳定性，可以结合传统对话系统中的意图识别、槽位提取、上下文管理和调用前确认：

1. 意图识别：判断用户要执行的任务。
2. 槽位提取：提取函数调用所需参数。
3. 上下文管理：维护多轮对话状态和历史信息。
4. 验证和确认：在调用前确认必要参数完整且意图正确。

RAG（Retrieval-Augmented Generation）结合检索和生成：先从外部知识库中检索相关内容，再把检索结果作为上下文交给 LLM 生成答案。

典型流程：

1. 准备数据并清洗无效内容。
2. 切分文档并生成向量。
3. 使用 ES 和向量数据库分别检索。
4. 对向量检索结果重排序。
5. 融合 ES 和向量检索结果。
6. 将问题和上下文组装为 prompt，提交给大模型。

Agent 示例主要关注：

• 工具调用是否稳定；
• 参数是否能被可靠抽取；
• 执行失败时如何捕获异常；
• 是否需要人工反馈来修正执行过程；
• 如何结合短期记忆和 RAG 提供上下文。

LLM 幻觉无法完全避免。demo 的价值不只是“让模型回答”，还包括通过可解释的检索、结构化输出、校验规则和可观察的中间步骤，帮助用户识别和降低幻觉风险。