---

Mirascope

欢迎来到 Mirascope，它使您能够通过一个统一的接口使用任何前沿的大型语言模型。

快速入门

安装 Mirascope：

uv add "mirascope[all]"

使用装饰器调用 LLM

from mirascope import llm


@llm.call("anthropic/claude-sonnet-4-5")
def recommend_book(genre: str):
    return f"推荐一本{genre}类的书。"


response = recommend_book("fantasy")
print(response.text())

获取结构化输出

from pydantic import BaseModel
from mirascope import llm


class Book(BaseModel):
    title: str
    author: str


@llm.call("anthropic/claude-sonnet-4-5", format=Book)
def recommend_book(genre: str):
    return f"推荐一本{genre}类的书。"


book = recommend_book("fantasy").parse()
print(f"{book.title} 作者：{book.author}")

构建带有工具的智能体

from pydantic import BaseModel
from mirascope import llm


class Book(BaseModel):
    title: str
    author: str


@llm.tool
def get_available_books(genre: str) -> list[Book]:
    """根据类型获取图书馆中可用的书籍"""
    return [Book(title="风之名", author="帕特里克·罗斯福斯")]


@llm.call("anthropic/claude-sonnet-4-5", tools=[get_available_books], format=Book)
def librarian(request: str):
    return f"你是一名图书管理员，请帮助用户：{request}"


response = librarian("我想要一本奇幻类的书")
while response.tool_calls:
    response = response.resume(response.execute_tools())
book = response.parse()
print(f"推荐：{book.title} 作者：{book.author}")

如需流式传输、异步对话、多轮对话等功能，请参阅完整文档。

单仓库结构

该项目采用单仓库结构，从概念上可分为四个部分：

• python/ 包含 Python 实现及示例（位于 python/examples）
• typescript/ 包含 TypeScript 实现及示例（位于 typescript/examples）
• website/ 包含营销网站（文档、博客、着陆页）
• docs/ 包含跨语言的统一文档（位于 docs/content），以及构建文档所需的配置

有关代码库结构、架构和设计决策的详细信息，请参阅 STRUCTURE.md。

网站开发

使用 bun run website:dev 启动开发服务器。

请注意，必须安装 Bun。

CI 和本地测试

我们目前有四条 CI 流程：

• codespell：检查包括 Python、TypeScript 和文档仓库在内的常见拼写错误
• python-lint：对 Python 代码进行 lint 检查和类型检查
• typescript-lint：对 TypeScript 代码进行 lint 检查和类型检查
• cloudflare docs build：构建并预览文档网站

您可以在根目录下运行 bun run ci 来在本地运行所有 CI 检查。如果要向 GitHub CI 添加新的检查，请同时将其添加到根目录下的 package.json 中的 CI 脚本中。

版本管理

Mirascope 使用 语义化版本控制。

许可证

本项目采用 MIT 许可证。

Mirascope 快速上手指南

Mirascope 是一个统一的接口库，允许开发者使用相同的代码模式调用各种前沿的大语言模型（LLM），支持结构化输出和工具调用（Agent）。

环境准备

• 操作系统：Linux、macOS 或 Windows
• Python 版本：3.9 及以上
• 包管理器：推荐使用 uv（高性能 Python 包安装器），也可使用 pip
• 依赖项：无特殊系统级依赖，需确保网络可访问模型提供商 API（如 Anthropic、OpenAI 等）

提示：国内开发者若遇到安装慢的问题，可配置国内镜像源。

• 使用 uv 时：export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
• 使用 pip 时：pip install ... -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

推荐使用 uv 进行安装，它将自动处理依赖和环境：

uv add "mirascope[all]"

如果习惯使用 pip，也可以使用以下命令：

pip install "mirascope[all]"

基本使用

1. 调用大模型

通过简单的装饰器即可调用模型。以下示例使用 Anthropic 的 Claude 模型推荐书籍：

from mirascope import llm


@llm.call("anthropic/claude-sonnet-4-5")
def recommend_book(genre: str):
    return f"Recommend a {genre} book."


response = recommend_book("fantasy")
print(response.text())

2. 获取结构化输出

结合 Pydantic 模型，让 LLM 直接返回格式化的 JSON 数据：

from pydantic import BaseModel
from mirascope import llm


class Book(BaseModel):
    title: str
    author: str


@llm.call("anthropic/claude-sonnet-4-5", format=Book)
def recommend_book(genre: str):
    return f"Recommend a {genre} book."


book = recommend_book("fantasy").parse()
print(f"{book.title} by {book.author}")

3. 构建带工具的 Agent

定义工具函数并让模型自主调用，实现简单的 Agent 逻辑：

from pydantic import BaseModel
from mirascope import llm


class Book(BaseModel):
    title: str
    author: str


@llm.tool
def get_available_books(genre: str) -> list[Book]:
    """Get available books in the library by genre."""
    return [Book(title="The Name of the Wind", author="Patrick Rothfuss")]


@llm.call("anthropic/claude-sonnet-4-5", tools=[get_available_books], format=Book)
def librarian(request: str):
    return f"You are a librarian. Help the user: {request}"


response = librarian("I want a fantasy book")
while response.tool_calls:
    response = response.resume(response.execute_tools())
book = response.parse()
print(f"Recommending: {book.title} by {book.author}")

注意：使用前请确保已配置对应模型提供商的 API Key（通常通过环境变量设置，如 ANTHROPIC_API_KEY）。