Semantic Kernel Python 开发环境搭建指南基于 uv 的安装、测试与代码质量全流程【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel本文面向需要在本地为 Semantic Kernel Python SDK 贡献新特性、修复 Bug或希望直接运行仓库内单元测试与集成测试的开发者完整讲解基于uv的开发环境搭建、VSCode 调试配置、LLM 密钥管理、测试运行、Pydantic 序列化改造与代码质量检查的整套流程。读完本文你将能够在本地一键复现官方开发环境并掌握 Semantic Kernel Python 仓库的工程化规范与核心实现约定。环境准备系统要求与 WSL 注意事项支持的操作系统Semantic Kernel Python 的开发环境支持 Windows含 WSL、macOS 与 Linux。仓库的 Python 项目配置见 pyproject.toml明确声明其支持的环境覆盖darwin、linux与win32三个平台因此无论你使用哪类系统均可按本文流程操作。使用 WSL 的开发者请注意如果你在 Windows 上通过 WSL 进行开发官方文档给出两条关键建议将仓库克隆到 WSL 用户目录建议克隆到~/workspace或类似目录避免放在/mnt/c/挂载路径下。WSL 访问 Windows 文件系统/mnt/c/存在明显的 I/O 性能开销且文件权限、符号链接等行为与原生 Linux 文件系统存在差异会影响uv虚拟环境与依赖安装的稳定性。安装 VSCode 的 WSL 扩展在 VSCode 中安装 WSL 扩展后可以直接从 Windows 侧连接 WSL 环境进行编辑与调试获得接近原生 Linux 的开发体验。使用 uv 管理环境为什么选择 uvSemantic Kernel Python 仓库采用 uv 作为包管理与虚拟环境工具。uv 的核心优势在于它允许你直接从本地源码使用 Semantic Kernel而无需关心 Python 路径问题效果等同于将 SK 作为 pip 包安装但所有代码改动即时生效非常适合源码级开发与调试。使用 uv 的另一个好处是Semantic Kernel 本身是 Python 生态中典型的异步优先 多可选依赖项目其依赖与可选依赖组见 pyproject.tomluv 的 lockfile 机制仓库根目录存在 uv.lock能保证团队与 CI 环境的依赖完全一致。一键安装make install在开始前先进入python目录即本文档所在目录。Mac 与 Linux含 WSL下最快捷的方式是运行make install这条命令会依次完成四件事对应 python/Makefile 中的install目标make install-uv安装 uv若已存在则执行uv self update自更新make install-python通过uv python install 3.10 3.11 3.12 3.13安装多个 Python 发行版python/Makefilemake install-sk创建虚拟环境并安装 Semantic Kernel 及其全部依赖make install-pre-commit安装 pre-commit 钩子。默认使用Python 3.10创建虚拟环境。如需更换版本通过PYTHON_VERSION环境变量指定make install PYTHON_VERSION3.12ℹ️注意运行install或install-sk会清除你现有的虚拟环境并重新创建。如果你的虚拟环境中安装有其他项目依赖请先确认是否需要保留。细看 Makefile各目标的职责边界make install实际上是四个子目标的组合。在需要精细化控制时可以单独执行Make 目标作用对应 Makefile 位置install-uv安装/更新 uv若检测到当前处于虚拟环境中则安装到$VIRTUAL_ENV/binpython/Makefileinstall-python安装 3.10/3.11/3.12/3.13 四个 Python 版本python/Makefileinstall-skuv venv --python $(PYTHON_VERSION)建虚拟环境 uv sync --all-extras --dev --prereleaseif-necessary-or-explicit装依赖python/Makefileinstall-pre-commit以python/.pre-commit-config.yaml为配置安装 git 钩子python/Makefileclean删除.venv虚拟环境目录python/Makefilebuild使用uvx --from build pyproject-build --installer uv构建项目产物python/Makefile如果只想更换 Python 版本而不重装 uv、Python 与 pre-commit可单独执行make install-sk PYTHON_VERSION3.12值得一提的是install-sk实际执行的同步命令是uv sync --all-extras --dev --prereleaseif-necessary-or-explicit。其中--all-extras会安装pyproject.toml中全部可选依赖组Anthropic、Azure、Chroma、Google、Ollama、Milvus、Qdrant、Redis、Weaviate 等 30 组见 python/pyproject.toml--dev安装 dev 依赖组pytest、mypy、ruff、pre-commit、ipykernel 等--prereleaseif-necessary-or-explicit则允许在必要时解析预发布版本。Windows非 WSL下的安装方式Windows 下先参照 uv 官方安装文档安装 uv写作时对应的命令为powershell -c irm https://astral.sh/uv/install.ps1 | iex然后手动执行以下命令PowerShell 中同样适用# 安装 Python 3.10、3.11 和 3.12 uv python install 3.10 3.11 3.12 # 使用 Python 3.10 创建虚拟环境可改为 3.11 或 3.12 $PYTHON_VERSION 3.10 uv venv --python $PYTHON_VERSION # 安装 SK 及全部依赖 uv sync --all-extras --dev # 安装 pre-commit 钩子 uv run pre-commit install -c python/.pre-commit-config.yaml如果你在 Windows 上安装了make如 GnuWin32 提供的版本也可以直接遵循上面 Mac/Linux 的make install流程。VSCode 开发环境配置基础配置安装 VSCode 的 Python 扩展。打开工作区。Python 工作区应根植于./python目录——这是因为该目录下同时存在pyproject.toml、uv.lock、mypy.ini等工程配置将工作区根目录设为python才能让 VSCode 正确识别项目配置。打开任意.py文件通过命令面板CtrlShiftP执行Python: Select Interpreter选择由 uv 创建的虚拟环境默认路径为.venv。如果提示安装ruff直接确认即可它已在uv sync --dev阶段随 dev 依赖安装。ruff 格式化与自动修复仓库的代码质量强依赖 ruff 中值得注意的配置包括行长度限制为120 字符line-length 120目标 Python 版本为py310target-version py310启用了 pydocstyleD、pyflakesF、isortI、copyrightCPY、flake8-returnRET等十余类规则pydocstyle 采用Google 风格convention google与下文文档规范一节相呼应copyright 规则要求文件首行为# Copyright (c) Microsoft. All rights reserved.notice-rgx见 python/pyproject.toml。配置单元测试框架仓库不再强制要求使用pytest也不再通过.vscode/settings.json强绑定测试框架开发者可以自由选择pytest或unittest。如需调整可通过命令面板CtrlShiftP执行Preferences: Open User Settings (JSON)在 VSCode 的本地settings.json中配置例如使用 pytestpython.testing.unittestEnabled: false, python.testing.pytestEnabled: true,或者使用 unittestpython.testing.unittestEnabled: true, python.testing.pytestEnabled: false,VSCode 内置任务仓库在 python/.vscode/tasks.json 中预置了一系列开发任务可通过命令面板Tasks: Run Task直接调用包括Python: Install执行make install内置 Python 版本选择器默认 3.10见 python/.vscode/tasks.jsonPython: Run Checks对全项目执行 pre-commit 检查Python: Run Checks - Staged仅对暂存文件执行检查Python: Run Mypy执行uv run mypy -p semantic_kernel --config-file mypy.iniPython: Tests - Unit/Python: Tests - Code Coverage/Python: Tests - All运行单元测试、覆盖率测试与全部测试。LLM 配置密钥、端点与模型 ID 管理要真正运行依赖 AI 服务的示例与集成测试你需要准备OpenAI API Key或Azure OpenAI 服务密钥。Semantic Kernel Python 提供了两种管理密钥/端点的方式方式一环境变量SK Python 基于Pydantic Settings从环境变量加载密钥与端点。当你在 VSCode 中配置好 Python 扩展后它会自动从.env文件加载环境变量无需手动在终端设置而在不同平台的部署环境中则应使用部署环境自带的环境变量配置。方式二独立的.env文件你也可以将配置存放于独立的.env文件如dev.env然后在构造大多数服务时通过env_file_path参数传入文件名。注意不要把*.env文件提交到仓库并确保它们已加入.gitignore。底层实现KernelBaseSettings 的加载优先级从源码看环境变量的加载逻辑封装在 python/semantic_kernel/kernel_pydantic.py 的KernelBaseSettings类中。该类通过__new__动态设置env_prefix、env_file默认.env与env_file_encoding默认utf-8其字段取值优先级从高到低为传入 Settings 类构造器的参数环境变量如OPENAI_API_KEYdotenv.env文件中加载的变量secrets 目录中的变量Settings 模型字段的默认值。这意味着即使环境变量与.env文件同时存在环境变量也会胜出便于在部署时通过环境变量覆盖本地配置。配置示例OpenAI Chat Completions在python目录根下创建openai.env文件名仅作示例实际项目中更常见的是将所有必需密钥集中在一个.envOPENAI_API_KEY OPENAI_CHAT_MODEL_IDgpt-4o-mini然后在代码中通过env_file_path指定该文件chat_completion OpenAIChatCompletion(service_idtest, env_file_pathopenai.env)更多设置的完整清单SK 涉及的设置项远不止以上两个完整清单见 ALL_SETTINGS.md涵盖AI 服务OpenAIOPENAI_CHAT_MODEL_ID、OPENAI_TEXT_MODEL_ID、OPENAI_EMBEDDING_MODEL_ID、OPENAI_TEXT_TO_IMAGE_MODEL_ID等、Azure OpenAIAZURE_OPENAI_CHAT_DEPLOYMENT_NAME、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_VERSION、Anthropic、Bedrock、Google AI、Vertex AI、HuggingFace、NVIDIA NIM、Mistral AI、Ollama、Onnx 等Agent 框架OPENAI_RESPONSES_MODEL_ID、AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME、AZURE_AI_AGENT_*、BEDROCK_AGENT_*、COPILOT_STUDIO_AGENT_*等Memory 服务AstraDB、Azure AI Search、Azure Cosmos DB、MongoDB Atlas、Pinecone、Postgres、Redis、Weaviate 等其他Bing 搜索BING_API_KEY、Azure Container Apps SessionsACA_POOL_MANAGEMENT_ENDPOINT等。每个服务都对应一个 Settings 类如 OpenAISettings、AzureOpenAISettings它们均继承自KernelBaseSettings。运行测试单元测试单元测试位于 python/tests/unit 目录共 270 个测试文件覆盖 AI 连接器、Functions、Memory、PromptTemplate、TemplateEngine 等模块运行命令uv run pytest tests/unit也可以通过 VSCode 任务执行命令面板CtrlShiftP→Tasks: Run Task选择Python: Tests - Unit或Python: Tests - Code Coverage。集成测试集成测试位于 python/tests/integration 目录它们需要真实的 AI 服务或向量数据库运行前请确认已按上文完成 LLM 配置uv run pytest tests/integration运行全部测试uv run pytest tests或通过Python: Tests - All任务运行该任务会启用 pytest-xdist 的-n logical并行分发见 python/.vscode/tasks.json。pytest 的相关默认配置位于 pyproject.toml默认testpaths tests启用asyncio_mode auto配合pytest-asyncio并设置 120 秒超时。实现约定异步编程与文档规范异步优先Semantic Kernel Python 的大部分代码以异步为设计核心。开发者在阅读与编写代码时应默认一切都是异步的。判断某个函数是否异步直接看函数签名是async def还是def即可。因此在编写插件函数或自定义服务时应优先考虑async def实现。Google Docstring 规范每个源文件的首行必须是版权声明# Copyright (c) Microsoft. All rights reserved.函数与方法遵循 Google Docstring 风格指南该规范与 ruff 的convention google配置一致当前不强制检查以_开头的私有函数。docstring 应包含首行一句话说明函数功能以句号结尾补充说明可选如需进一步解释逻辑在首行后换行展开Args:可选每个参数按arg_name: 说明 的格式列出参数需要更长解释时换行并缩进 4 个空格类型与默认值无需写出会从函数定义中自动提取Returns:或Yields:可选说明返回类型与返回值含义Raises:可选每个异常按ExceptionType: 说明 的格式列出长说明同样换行缩进 4 空格。最小示例def equal(arg1: str, arg2: str) - bool: Compares two strings and returns True if they are the same. ...完整示例def equal(arg1: str, arg2: str) - bool: Compares two strings and returns True if they are the same. Here is extra explanation of the logic involved. Args: arg1: The first string to compare. arg2: The second string to compare. This string requires extra explanation. Returns: True if the strings are the same, False otherwise. Raises: ValueError: If one of the strings is empty. ...如有疑问优先参考上述 Google 风格指南链接或遵循项目中的惯例。Pydantic 与序列化Semantic Kernel Python 大量使用 Pydantic v2 做模型定义与序列化。仓库为此提供了统一的基类KernelBaseModel定义于 python/semantic_kernel/kernel_pydantic.py它配置了populate_by_nameTrue允许按字段名或别名填充、arbitrary_types_allowedTrue允许任意类型字段与validate_assignmentTrue赋值时校验。更多细节可参考 Pydantic 官方文档。将现有类升级为 Pydantic 类以如下普通类为例class A: def __init__(self, a: int, b: float, c: List[float], d: dict[str, tuple[float, str]] {}): self.a a self.b b self.c c self.d d将其转换为 Pydantic 类只需继承KernelBaseModel字段声明风格与 dataclass 类似可变默认值改用Field(default_factory...)from pydantic import Field from semantic_kernel.kernel_pydantic import KernelBaseModel class A(KernelBaseModel): # 字段声明风格与 dataclass 类似 a: int b: float c: list[float] # 与 dataclasses.field 对应的是 pydantic.Field d: dict[str, tuple[float, str]] Field(default_factorydict)含泛型类型的序列化当类中某些字段是泛型类型时必须把类型变量同时声明在Generic[...]参数中否则 Pydantic无法对该类进行序列化from typing import Generic, TypeVar from semantic_kernel.kernel_pydantic import KernelBaseModel T1 TypeVar(T1) T2 TypeVar(T2, boundsome class) class A(KernelBaseModel, Generic[T1, T2]): # T1 和 T2 必须出现在 Generic 参数中否则 pydantic 无法序列化该类 a: int b: T1 c: T2代码质量检查pre-commit 钩子安装环境时install-pre-commit已自动配置钩子但在提交前仍建议手动执行一次全量检查命令与 CI 中的Python Code Quality ChecksGitHub Action 完全一致在python目录下执行uv run pre-commit run -a也可通过 VSCode 任务运行Python - Run Checks全项目或Python - Run Checks - Staged仅暂存文件。pre-commit 的实际配置见 python/.pre-commit-config.yaml主要钩子包括pre-commit-hooksv4.6.0check-toml、check-yaml、check-json、end-of-file-fixer、mixed-line-ending、debug-statements、check-ast含 Python 示例校验nbQA1.8.5nbqa-check-ast校验 Jupyter Notebook 的语法有效性pyupgradev3.17.0自动升级至--py310-plus语法ruff-pre-commitv0.9.6ruff带--fix --exit-non-zero-on-fix与ruff-format自动格式化uv-pre-commit0.5.30uv-lock在pyproject.toml变更时同步更新 lockfilebandit1.7.10基于python/pyproject.toml中的[tool.bandit]配置做安全扫描目标为semantic_kernel排除tests与samples/demos/mcp_with_oauth。此外仓库还通过 ruff 的CPY规则强制每个.py文件带版权头python/pyproject.toml以及使用 mypy 做静态类型检查配置见 python/mypy.ini。代码覆盖率项目力求维持较高的单元测试覆盖率。在单元测试上运行覆盖率统计的命令uv run pytest --covsemantic_kernel --cov-reportterm-missing:skip-covered tests/unit/或使用 VSCode 任务Python: Tests - Code Coverage。该命令会列出未被测试覆盖的文件及其具体未覆盖行号。建议重点关注你正在修改的代码的未覆盖行当然也非常欢迎为其他代码补充测试。同步上游最新更改Semantic Kernel 的提交非常活跃保持本地仓库与上游同步十分重要。假设upstream指向主仓库有两种同步方式方式一rebase推荐历史更干净git fetch upstream main git rebase upstream/main git push --force-with-lease方式二mergegit fetch upstream main git merge upstream/main git push如果upstream名称与你的远程命名不同将命令中的upstream替换为你实际的远程名即可。执行 rebase 后可能需要手动解决冲突冲突解决可参考 GitHub 官方文档中关于 rebase 冲突解决的说明或使用 VSCode 的合并冲突视图Source Control 面板。小结至此一套完整的 Semantic Kernel Python 开发环境已经就绪从make install一键安装 uv/Python/依赖/pre-commit到 VSCode 的解释器与 ruff 配置再到 LLM 密钥的.env管理、单元/集成测试的运行、Pydantic 序列化改造与代码质量检查。这套流程既服务于日常的功能开发与 Bug 修复也是参与 Semantic Kernel 社区贡献前必须掌握的工程化基础。相关配置与实现的入口文件均已在上文给出可随时回到仓库中对照查阅。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考