内容
# 知识来源
> 查询时MCP和Fabric本体基线验证：查看哪些实时来源给出了答案，哪些工具运行了，哪些引用回来了。
[](LICENSE)
一个知识库可以将查询路由到实时的MCP工具和受管制的Fabric语义，然后返回跟踪合约：`activity`、`references`和`sourceData`。
**🎬 查看实际操作** — 从 `git clone` 到验证部署的约5分钟演练（`clone → local mock → test → deploy → verify → cleanup`），并附有演示应用的实际录像和执行笔记本（离线/干燥运行 - 屏幕上无密钥）。
[](../../releases/tag/walkthrough-v1)
⬇ 下载完整视频： [English (5 min)](../../releases/download/walkthrough-v1/repo-quickstart-guide-en.mp4) · [한국어 (5분)](../../releases/download/walkthrough-v1/repo-quickstart-guide.mp4) · [章节和如何重建](video-guide/README.md)
## 这是什么
- **MCP服务器知识源** 在知识库检索期间在远程HTTPS MCP服务器上调用允许的工具。
- **Fabric本体知识源** 通过委派源授权，将答案落实在受管制的Fabric语义中。
- **一个知识库** 可以跨多个源路由并返回可检查的 `activity`、`references` 和 `sourceData`。
这是一个可重复使用的示例加速器，而不是生产参考架构。它使用Azure AI Search公共预览版知识源API（`2026-05-01-preview`）。在预览行为演变过程中，请将[官方学习手册](#primary-manuals)作为真实来源。
## 为什么有这个仓库
- **查看跟踪，而不仅仅是文档。** 离线响应显示实际的检索合约：哪个源运行，哪个工具被调用，哪些证据返回。
- **在30秒内运行，无需设置。** 在没有Azure密钥、租户访问或Fabric工作区的情况下了解合约。
- **一键部署。** 当准备好时，从离线重放切换到 `mcp-only`、`byo-fabric` 或 `full` 部署路径。
此仓库通过围绕相同预览API的可运行有效载荷、笔记本、部署脚本和离线证据来补充官方学习手册。
## 您将学习的内容
1. 在没有云设置的情况下检查离线检索跟踪。
2. 在笔记本中遍历MCP服务器KS和Fabric本体KS。
3. 部署实时演示应用，并针对租户验证相同的跟踪合约。
## 30秒内试用
无需Azure订阅、密钥、租户或Fabric工作区：
```bash
python3 samples/python/inspect_retrieve_response.py samples/responses/mcp-retrieve.sample.json
```
您应该看到 `Activity`、`References` 和 `Source Data Preview` 部分。
尝试组合离线跟踪：
```bash
python3 samples/python/inspect_retrieve_response.py samples/responses/combined-airline-ops-retrieve.sample.json
```
它显示了航空公司运营业务数据的Fabric本体活动和Microsoft Learn实施指导的MCP服务器活动。
## 部署实时演示
选择与您的租户状态匹配的路径。
| 模式 | 使用场景 | 命令 |
| --- | --- | --- |
| `mcp-only` | 您希望在没有Fabric的情况下进行最快的实时验证。 | `bash scripts/deploy.sh --mode mcp-only --env-name liveks-mcp --location eastus` |
| `byo-fabric` | 您已经有一个Fabric工作区和本体。 | `bash scripts/deploy.sh --mode byo-fabric --env-file .env.external.local --env-name liveks-byo --location eastus` |
| `full` | 您希望创建一个绿地运行，首先创建示例Fabric资产。 | `bash scripts/deploy.sh --mode full --env-name liveks-full --location eastus --fabric-location westus3` |
在部署之前，安装 `azd`、`az`、`python3`、`node` 和 `npm`，然后登录。参见 [部署前提条件](docs/10-one-command-deployment.md#prerequisites)。
默认应用是Azure静态Web应用和托管函数API。浏览器代码永远不会接收搜索管理员密钥或Azure OpenAI密钥。
安全默认值：部署包装器在预配之前验证模板、有效载荷和应用；失败的部署会打印清理命令；生成的Fabric ID会保存以备拆除；`destroy.sh`继续执行`azd down --purge --force`，即使Fabric清理需要手动跟进。
应用是一种查看相同跟踪合约的方式。它按阶段显示响应，以便您在演示期间解释查询、答案、源活动、引用和源数据。对于更长的演示流程，请参见[演示演练](docs/16-demo-walkthrough.md)。
## 工作原理
知识库组成实时源。每个检索调用都可以通过 `knowledgeSourceParams` 提示使用哪些源，然后响应会公开 `activity`、`references` 和 `sourceData`。
<p align="center">
<img src="assets/how-it-works.gif"
alt="One retrieve call against a Knowledge Base composes a live MCP Server source and a Fabric Ontology source, then returns an inspectable trace contract: activity, references, sourceData."
width="900">
</p>
每条路径都遵循相同的循环：
```text
创建知识源
-> 将其附加到知识库
-> 使用测试问题检索
-> 检查活动、引用和源数据
```
示例使用合成的航空公司运营领域，包含虚构的航空公司名称和真实的机场地理信息。它对于公共演示是安全的，同时展示了现实的语义连接和跟踪行为。
## 创建内容
| 路径 | 知识源 | 其他资产 |
| --- | --- | --- |
| `mcp-only` | Microsoft Learn MCP服务器KS | Azure AI Search、Azure OpenAI、MCP-only KB、搜索索引、演示应用 |
| `byo-fabric` | MCP服务器KS + Fabric本体KS | `mcp-only`中的所有内容，加上连接到您的Fabric本体的组合KB |
| `full` | MCP服务器KS + 生成的Fabric本体KS | Fabric容量/工作区/数据湖/本体/图模型、Azure资源、组合KB、演示应用 |
生成的部署日志和报告保留在忽略的路径下，例如 `.deployment/` 和 `deployments/`。
## 了解更多
| 需要 | 从这里开始 |
| --- | --- |
| 选择部署路径 | [选择模式](docs/02-choose-a-pattern.md) |
| 了解架构 | [架构](docs/01-architecture.md) |
| 学习MCP服务器KS | [MCP服务器知识源](docs/03-mcp-server-ks.md) |
| 学习Fabric本体KS | [Fabric本体知识源](docs/04-fabric-ontology-ks.md) |
| 了解组合路由 | [组合知识库路由](docs/05-combined-kb-routing.md) |
| 运行一键部署 | [一键演示部署](docs/10-one-command-deployment.md) |
| 连接现有的Fabric资产 | [Fabric实时BYO验证](docs/11-fabric-live-byo-validation.md) |
| 检查离线跟踪 | [离线重放](docs/09-offline-replay.md) |
| 排查设置和检索问题 | [故障排除](docs/07-troubleshooting.md) |
| 查看常见问题 | [常见问题](docs/19-faq.md) |
| 查看预览限制 | [公共预览限制](docs/13-public-preview-limitations.md) |
## 主要手册
- [创建MCP服务器知识源](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-mcp-server)
- [创建Fabric本体知识源](https://learn.microsoft.com/azure/search/agentic-knowledge-source-how-to-fabric-ontology)
- [创建知识库](https://learn.microsoft.com/azure/search/agentic-retrieval-how-to-create-knowledge-base)
- [查询知识库](https://learn.microsoft.com/azure/search/agentic-retrieval-how-to-retrieve)
## 仓库地图
```text
docs/ 概念、部署、故障排除和FAQ
infra/ Azure AI Search、Azure OpenAI、Storage和应用托管的Bicep
scripts/ 部署、销毁、E2E、Fabric、验证和后置部署助手
static-app/ Azure静态Web应用和函数演示应用
samples/rest/ 原始REST请求序列
samples/python/ 用于有效载荷生成和跟踪检查的小型帮助器脚本
samples/responses/ 离线检索响应
samples/data/ 合成航空公司运营数据
samples/ontology/ 航空公司运营本体合约
notebooks/ 有指导的MCP和Fabric教程
src/ks_factory/ 可重复使用的Python有效载荷构建器
assets/ 图表和演示截图
```
## 本地验证
在打开PR或广泛共享示例之前运行此操作：
```bash
bash scripts/validate-local.sh
```
网关检查shell语法、Python编译、Python合约测试、笔记本JSON、Markdown链接、示例卫生、有效载荷生成、离线响应、无密钥扫描、静态Web应用构建和Bicep构建（当Azure CLI可用时）。
## 安全说明
- 不要提交租户ID、服务URL、API密钥、承载令牌、原始实时响应、生成的部署报告或具有敏感值的本地截图。
- MCP服务器KS需要远程HTTPS MCP服务器。不能直接附加本地stdio MCP服务器。
- Fabric实时检索需要 `x-ms-query-source-authorization` 中的原始最终用户搜索访问令牌；不要在其前面添加 `Bearer`。
- 离线重放用于学习跟踪形状。它不是Fabric实时检索的证明。
## 贡献
欢迎提出问题和PR。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)、 [SECURITY.md](SECURITY.md) 和 [SUPPORT.md](SUPPORT.md)。
该项目根据 [MIT License](LICENSE) 许可。
连接信息
猜你喜欢
暂无推荐服务器