aisuite 多 Provider 接入指南从 API Key 申请到首个 Chat Completion【免费下载链接】aisuiteSimple, unified interface to multiple Generative AI providers项目地址: https://gitcode.com/GitHub_Trending/ai/aisuite本指南以 aisuite 官方guides/文档为主线系统梳理 20 云端与本地推理 Provider 的 API Key 获取、环境变量配置与代码调用方式并结合仓库源码说明 aisuite 统一接口背后的 Provider 自动发现与参数解析机制。读完本文你将能在一小时内为任意一个受支持的模型供应商完成环境配置并跑通第一个 Chat Completion 请求。概览一份文档多个供应商aisuite 的核心设计理念是通过修改一个字符串来切换供应商模型名统一使用provider:model-name格式例如openai:gpt-4o库内部负责把请求路由到正确的供应商并完成参数适配。因此接入不同供应商的唯一前置差异就是如何拿到 API Key 以及把它配置到哪里——这正是 guides/README.md 这份指南索引所要解决的问题。整个指南目录覆盖两类接入场景云端托管供应商Anthropic、AWS、Azure、Cohere、Gemini、Google、Groq、Hugging Face、Mistral、OpenAI、Featherless、SambaNova、xAI、DeepSeek、Eden AI、Cerebras、Nebius、Crusoe、Tongyi、Watsonx 等均需要申请 API Key 并写入环境变量本地托管模型Ollama 与 LM Studio无需任何 API Key只需在ai.Client(provider_configs...)中指定服务地址。除非另有说明这些指南均未获得各供应商的官方背书指南原文明确注明。仓库同时欢迎社区贡献新的 Provider 指南详见 CONTRIBUTING.md。统一调用骨架所有 Provider 共享的代码形态无论选择哪个供应商最终的代码结构几乎完全一致。以 guides/openai.md 中的完整示例为骨架import aisuite as ai client ai.Client() provider openai model_id gpt-4-turbo messages [ {role: system, content: You are a helpful assistant.}, {role: user, content: Whats the weather like in San Francisco?}, ] response client.chat.completions.create( modelf{provider}:{model_id}, messagesmessages, ) print(response.choices[0].message.content)这段代码有三个关键要素ai.Client()统一客户端入口。默认情况下它会自动读取各供应商约定的环境变量见下文各节也支持通过provider_configs参数显式传入配置。modelf{provider}:{model_id}双段式模型名。冒号前的provider是路由键冒号后是该供应商内部的模型标识符Model ID / 部署名。response.choices[0].message.content统一响应结构。无论底层是 OpenAI、Anthropic 还是 AWS Bedrock响应对象都被归一化为 OpenAI 风格。从源码看模型名的解析发生在ProviderFactory中。aisuite/provider.py的get_supported_providers()方法会扫描aisuite/providers/目录下所有*_provider.py文件并动态加载对应的 Provider 类这就是新增 Provider 只需按_provider.py命名约定添加模块这一扩展机制README 中有明确说明的底层实现。而aisuite/client.py中的_validate_provider_key会在遇到未知前缀时抛出ValueError并列出全部受支持供应商提示检查模型字符串格式。安装方式按 README.md 的说明可只装基础包、按需附带特定供应商 SDK或一次装齐pip install aisuite # 基础包不含任何供应商 SDK pip install aisuite[anthropic] # 附带指定供应商的 SDK pip install aisuite[all] # 附带所有供应商 SDK下文各指南中出现的pip install openai、pip install boto3等命令实质就是按需补装该供应商 SDK的等价做法。云端托管供应商API Key 申请与环境变量速查下表汇总了 guides/ 目录下各云端供应商指南的要点。环境变量命名遵循供应商前缀 API_KEY的统一约定绝大多数供应商只需设置一个变量即可。Provider指南文档API Key 申请入口环境变量需安装的 SDKOpenAIguides/openai.mdplatform.openai.com → API KeysOPENAI_API_KEYopenaiAnthropicguides/anthropic.mdconsole.anthropic.com → API KeysANTHROPIC_API_KEYanthropicAWS Bedrockguides/aws.mdAWS Console → Bedrock → 启用基础模型AWS_ACCESS_KEY/AWS_SECRET_KEY/AWS_REGION可选默认us-west-2boto3Azure AIguides/azure.mdAzure Portal AI Studio 部署模型AZURE_API_KEY/AZURE_BASE_URL/AZURE_API_VERSIONopenaiCohereguides/cohere.mddashboard.cohere.com → API KeysCO_API_KEYcohereGemini开发者 APIguides/gemini.mdGoogle AI Studio → Create API keyGEMINI_API_KEYGOOGLE_API_KEY兜底aisuite[gemini]GoogleVertex AIguides/google.mdGoogle Cloud Console → 服务账号GOOGLE_PROJECT_ID/GOOGLE_REGION/GOOGLE_APPLICATION_CREDENTIALSvertexaiGroqguides/groq.mdconsole.groq.com → API KeysGROQ_API_KEYgroqHugging Faceguides/huggingface.mdHF 账号 → Settings → TokensHF_TOKENhuggingfaceMistralguides/mistral.mdconsole.mistral.ai → API KeysMISTRALmistralaixAIguides/xai.mdconsole.x.aiXAI_API_KEYopenaiDeepSeekguides/deepseek.mdplatform.deepseek.com → API KeysDEEPSEEK_API_KEYopenaiEden AIguides/edenai.mdapp.edenai.run → 生成 KeyEDENAI_API_KEYopenaiSambaNovaguides/sambanova.mdcloud.sambanova.ai → APISAMBANOVA_API_KEYopenaiCerebrasguides/cerebras.mdcloud.cerebras.aiCEREBRAS_API_KEYopenaiNebiusguides/nebius.mdstudio.nebius.ai → API KeysNEBIUS_API_KEYopenaiCrusoeguides/crusoe.mdconsole.crusoecloud.comCRUSOE_API_KEYopenaiFeatherlessguides/featherless.mdfeatherless.ai → API KeysFEATHERLESS_API_KEYopenaiTongyi通义千问guides/tongyi.md阿里云百炼控制台TONGYI_API_KEYaisuite[all]Watsonxguides/watsonx.mdIBM Cloud IAM → API keysWATSONX_API_KEY/WATSONX_SERVICE_URL/WATSONX_PROJECT_IDibm-watsonx-ai通用流程以 Groq 为例绝大多数云端供应商遵循同一条操作路径guides/groq.md 描述得最为典型注册账号并登录控制台进入 API Keys 页面生成一个新 Key将 Key 导出为环境变量export GROQ_API_KEYyour-groq-api-key安装对应 SDK 并调用统一接口import aisuite as ai client ai.Client() provider groq model_id llama-3.2-3b-preview # 可替换为 Groq 控制台列出的任意模型 messages [ {role: system, content: You are a helpful assistant.}, {role: user, content: Whats the weather like in San Francisco?}, ] response client.chat.completions.create( modelf{provider}:{model_id}, messagesmessages, ) print(response.choices[0].message.content)环境变量是如何被读取的以 Groq 为例aisuite/providers/groq_provider.py 中self.api_key config.get(api_key, os.getenv(GROQ_API_KEY))这行代码显示Provider 构造时优先取provider_configs里显式传入的api_key缺省时回落到环境变量两者皆无则抛出异常提示。OpenAI Provider 的 aisuite/providers/openai_provider.py 也采用完全相同的config.setdefault(api_key, os.getenv(OPENAI_API_KEY))模式。这解释了为什么本文所有示例都只需导出环境变量 ai.Client()两件事。两类特殊配置形态1. OpenAI 兼容型供应商需要openaiSDKDeepSeek、Eden AI、SambaNova、Nebius、Crusoe、Featherless、Cerebras 等供应商的指南中都有一个共同注释该服务使用与 OpenAI 一致的 API 格式因此需要安装openai客户端目前没有独立的官方库。典型示例来自 guides/deepseek.mdpip install openaiimport aisuite as ai client ai.Client() provider deepseek model_id deepseek-chat messages [ {role: system, content: You are a helpful assistant.}, {role: user, content: Whats the weather like in San Francisco?}, ] response client.chat.completions.create( modelf{provider}:{model_id}, messagesmessages, ) print(response.choices[0].message.content)其中 Eden AI 稍有不同它是欧盟托管的 OpenAI 兼容网关一个 Key 即可路由 100 模型模型名采用provider/model命名例如anthropic/claude-sonnet-4-5、mistral/codestral-latest在 aisuite 中写作edenai:anthropic/claude-sonnet-4-5。2. Gemini 开发者 API纯 Key、零 GCP 配置guides/gemini.md 特别强调gemini前缀走的是 Google Gemini Developer API仅需普通 API Key不需要 Google Cloud 项目、服务账号或 GCS bucket若要使用 Vertex AIGCP 项目认证则应改用google前缀并参照 guides/google.md。这正体现了 aisuite 中同一模型供应商可能有多个前缀的路由设计。export GEMINI_API_KEYyour-gemini-api-key pip install aisuite[gemini]import aisuite as ai client ai.Client() response client.chat.completions.create( modelgemini:gemini-2.5-flash, messages[{role: user, content: Tell me a joke.}], ) print(response.choices[0].message.content)从源码看aisuite/providers/gemini_provider.py 的 key 解析为os.getenv(GEMINI_API_KEY) or os.getenv(GOOGLE_API_KEY)与指南中GOOGLE_API_KEY作为兜底的说明完全对应。该指南还提示了 Gemini 的图片输入约束图片必须以 base64 data URLdata:image/png;base64,...形式放在 OpenAI 风格的image_url内容块中Gemini API 不会主动抓取普通 http(s) 图片链接。AWS Bedrock 与 Google Vertex云厂商专属流程这两个供应商不是生成一个 Key这么简单需要完整的云平台配置指南给出的步骤最详细。AWS Bedrockguides/aws.md创建 AWS 账号并进入 Bedrock 控制台示例区域为us-west-2可按需替换在 Model access 页面为账号启用要使用的基础模型在 Providers 页面选定具体模型记录页面底部的Model ID如meta.llama3-1-405b-instruct-v1:0后续代码中直接使用设置三个环境变量AWS_REGION可选默认us-west-2export AWS_ACCESS_KEYyour-access-key export AWS_SECRET_KEYyour-secret-key export AWS_REGIONregion-name安装boto3并调用。源码层面aisuite/providers/aws_provider.py 中self.region_name config.get(region_name, os.getenv(AWS_REGION, us-west-2))印证了指南中默认区域为 us-west-2的说法Provider 通过boto3.client(bedrock-runtime, ...)与 Bedrock 交互。Google Vertex AIguides/google.md注册 Google Cloud 账号并创建项目、启用结算设置GOOGLE_PROJECT_ID与GOOGLE_REGION两个环境变量在 IAM 服务账号页面创建服务账号为其创建 JSON 格式密钥文件下载后设置GOOGLE_APPLICATION_CREDENTIALS指向该文件确认三个环境变量齐备后安装vertexaiSDK 并调用export GOOGLE_PROJECT_IDyour-project-id export GOOGLE_REGIONyour-region export GOOGLE_APPLICATION_CREDENTIALSpath/to/your/service-account-file.json pip install vertexaiimport aisuite as ai client ai.Client() model google:gemini-1.5-pro-001 messages [ {role: system, content: Respond in Pirate English.}, {role: user, content: Tell me a joke.}, ] response client.chat.completions.create( modelmodel, messagesmessages, ) print(response.choices[0].message.content)Azure AIBase URL 与部署名强绑定guides/azure.md 的配置要点与前两者不同——它需要三个变量且对模型命名有严格要求在 Azure Portal 创建账号、项目和资源组在 AI Studio 选择一个模型如 Mistral-large-2407并部署可选择 serverless 部署部署名可自定义从 Endpoint 面板记录Target URI形如https://aisuite-Mistral-large-2407.westus3.models.ai.azure.com及其 Chat completion URL形如.../v1/chat/completions设置环境变量export AZURE_API_KEYyour-api-key export AZURE_BASE_URLhttps://deployment-name.region-name.models.ai.azure.com/v1 export AZURE_API_VERSION2024-08-01-previewAZURE_API_VERSION为可选配置主要面向 Azure OpenAI 服务一旦指定api-version查询参数会追加到请求末尾。这一点在 aisuite/providers/azure_provider.py 中有直接体现self.base_url config.get(base_url) or os.getenv(AZURE_BASE_URL)且base_url为必填项缺失时抛出提示请到部署页面查看形如https://模型部署名.区域.models.ai.azure.com的 URL请求 URL 为f{self.base_url}/chat/completions指定api_version时再拼接?api-version...。代码中还有两个易错点值得注意模型名必须与部署名一致。示例中的model azure:aisuite-Mistral-large-2407冒号后是部署名而非模型家族名ai.Client()参数会覆盖环境变量。指南原文明确Either set the environment variables or set the below two parameters. Setting the params in ai.Client() will override the values from environment vars.示例代码中还使用了os.environ[AZURE_OPENAI_BASE_URL]等变量名注意与上面AZURE_BASE_URL的对应关系。本地托管模型Ollama 与 LM Studio零 API Key如果不想申请任何云端 KeyOllama 和 LM Studio 提供了完全本地化的选择。二者共同特点是本地启动服务后直接通过provider_configs传入服务地址无需任何 API Key隐私数据不出本机。这也与 README.md 中 OpenWorker 桌面 Agent完全本地运行Ollama的定位一致。Ollamaguides/ollama.md先在本机启动 Ollama 服务默认地址http://localhost:11434指南示例中使用了局域网地址http://10.168.0.177:11434然后import aisuite as ai def main(): client ai.Client( provider_configs{ ollama: { base_url: http://10.168.0.177:11434, timeout: 300, } } ) messages [ {role: system, content: Be verbose}, {role: user, content: Tell me something about University of Michigans CSE department.}, ] ollama_llama3 ollama:llama3:latest ollama_gemma ollama:gemma:latest ollama_deepseek_32B ollama:deepseek-r1:32b ollama_deepseek_70B ollama:deepseek-r1:70b response client.chat.completions.create( modelollama_gemma, messagesmessages, temperature0.75, ) print(response.choices[0].message.content) if __name__ __main__: main()从源码看aisuite/providers/ollama_provider.py 的_parse_base_url函数会按base_url→api_url→OLLAMA_API_URL环境变量的顺序解析服务地址config.pop(base_url, None) or config.pop(api_url, None)并自动去除末尾/、补齐/v1路径后缀timeout则直接传给底层客户端300秒的设置适合大模型长推理场景。LM Studioguides/lmstudio.mdLM Studio 在本地提供 ChatGPT 风格的 Web 门户同时暴露 OpenAI 兼容的本地 API。默认服务地址为http://localhost:1234import aisuite as ai def main(): # Set the API URL to remote NGA2 server client ai.Client( provider_configs{ lmstudio: { api_url: http://localhost:1234, timeout: 300, } } ) messages [ {role: system, content: Be verbose}, {role: user, content: Tell me something about University of Michigans CSE department.}, ] lmstudio_llama lmstudio:llama-3.2-3b-instruct response client.chat.completions.create( modellmstudio_llama, messagesmessages, temperature0.75, ) print(response.choices[0].message.content) if __name__ __main__: main()指南中给出了预期的示例输出一段关于密歇根大学计算机科学与工程系的详细介绍可用作验证本地链路是否打通的参照。这里需要特别留意一个细节Ollama 配置键是base_urlLM Studio 是api_url。这是因为 Ollama 提供方内部做了归一化处理base_url/api_url二选一而 LM Studio 的 Provider 读取的是api_url键两者在各自指南中保持一致即可混用会导致配置不生效。本地与云端的统一体验对比上文所有代码可以发现本地模型与云端模型的唯一差别就是ai.Client()初始化时多传了provider_configs调用侧的modelprovider:model_id、messages、temperature、response.choices[0].message.content全部一致。这正是 aisuite 统一抽象的意义——同一套业务代码可以无缝在本地 Ollama 与云端 GPT-4 之间切换只需修改model字符串。provider_configs显式配置与覆盖优先级除了各指南展示的用法provider_configs机制本身值得展开说明。从 aisuite/client.py 的Client.__init__定义可见def __init__( self, provider_configs: Optional[dict] None, extra_param_mode: Literal[strict, warn, permissive] warn, ):provider_configs是一个以 provider 字符串为键、配置字典为值的映射例如{ openai: {api_key: your_openai_api_key}, aws-bedrock: { aws_access_key: your_aws_access_key, aws_secret_key: your_aws_secret_key, aws_region: us-west-2, }, }其覆盖语义为显式传入provider_configs的值优先于环境变量Azure 指南中的说明即是该语义的实例未显式给出的字段再回落到环境变量读取。configure()方法还允许在 Client 创建后增量补充配置。结合源码_initialize_providers可以看到每个 provider 配置会经由ProviderFactory.create_provider实例化为具体的 Provider 对象且为惰性初始化按需创建。另外aisuite/client.py 还暴露了extra_param_mode参数取值strict/warn/permissive用于控制对未知参数的校验严格度strict对未知参数直接抛ValueError适合生产、warn仅记录警告默认适合开发、permissive放行所有参数适合测试。这与指南中temperature0.75等参数的透传行为相关属于进阶调优选项。接入新供应商按命名约定扩展如果某个供应商不在上表中aisuite 的架构支持以极低成本自行接入。README.md 给出了明确的扩展约定元素约定模块文件provider_provider.py类名ProviderProvider首字母大写# providers/openai_provider.py class OpenaiProvider(BaseProvider): ...该约定保证了ProviderFactory的自动发现机制能正确加载新集成——它通过扫描aisuite/providers/目录下的*_provider.py文件并按其类名实例化无需修改工厂注册表。想验证某个前缀是否可用可直接调用ProviderFactory.get_supported_providers()查看当前仓库支持的全部供应商列表。结语aisuite 的 Provider 接入可以浓缩为三步拿到 Key → 导出环境变量 → 用provider:model调用统一接口。云端 20 家供应商共用同一套代码骨架本地 Ollama/LM Studio 仅需多传一个provider_configs真正的差异化全部被封装在aisuite/providers/各 Provider 模块内部。本文各供应商的详细步骤均可回溯至 guides/ 目录下的对应文档源码佐证见 aisuite/client.py客户端与配置解析与 aisuite/provider.pyProvider 工厂与自动发现。快速上手可继续阅读 docs/chat-completions-quickstart.md安装、Key 配置与更多示例以及 examples/client.ipynb可交互运行的示例 Notebook。【免费下载链接】aisuiteSimple, unified interface to multiple Generative AI providers项目地址: https://gitcode.com/GitHub_Trending/ai/aisuite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考