LLM
面向多个 LLM 提供方的统一接口,支持自动路由
概述#
LLM 抽象层提供与多个 AI 提供方的无缝集成,让你可以在 OpenAI、Claude、Gemini 和 Ollama 之间自由切换,而无需修改代码。它负责处理各提供方特有的实现、消息格式化和流式传输,同时对外提供统一一致的 API。
支持的提供方#
Astreus 支持四大主流 LLM 提供方,并具备自动模型路由能力:
示例显式选择模型;仍受支持的现有默认值保持不变。原生 API 中已停用的模型需要显式指定当前可用的替代模型。
OpenAI#
当前直连 API 模型 ID:
gpt-6-astragpt-5.6-solgpt-5.6-terragpt-5.6-luna- API 密钥:设置
OPENAI_API_KEY环境变量
直接请求 OpenAI 时,GPT-6 Astra 的工具调用需要 Responses API。适配器负责处理该协议;已配置的 OpenAI 兼容网关使用 Chat Completions。不要为 GPT-6 Astra 设置 temperature 或 top_p。请参阅 OpenAI 模型指南。
Anthropic Claude#
当前直连 API 模型 ID:
claude-fable-5-1claude-opus-5claude-sonnet-5claude-haiku-4-5-20251001- API 密钥:设置
ANTHROPIC_API_KEY环境变量
Google Gemini#
全部 12 个受支持的模型:
- 最新:
gemini-2.5-pro、gemini-2.5-pro-deep-think、gemini-2.5-flash、gemini-2.5-flash-lite - 稳定版:
gemini-2.0-flash、gemini-2.0-flash-thinking、gemini-2.0-flash-lite、gemini-2.0-pro-experimental、gemini-1.5-pro、gemini-1.5-flash、gemini-1.5-flash-8b、gemini-pro - API 密钥:设置
GEMINI_API_KEY环境变量
Ollama(本地)#
全部 31 个受支持的模型:
- 最新:
deepseek-r1、deepseek-v3、deepseek-v2.5、deepseek-coder、deepseek-coder-v2、qwen3、qwen2.5-coder、llama3.3、gemma3、phi4 - 常用:
mistral-small、codellama、llama3.2、llama3.1、qwen2.5、gemma2、phi3、mistral、codegemma、wizardlm2 - 其他:
dolphin-mistral、openhermes、deepcoder、stable-code、wizardcoder、magicoder、solar、yi、zephyr、orca-mini、vicuna - 配置:设置
OLLAMA_BASE_URL(默认:http://localhost:11434)
配置#
环境变量#
配置你的 API 密钥和相关设置:
仅通过 shell 环境变量或密钥管理服务提供所用提供方的凭据。以下命令读取已有的环境变量值,不包含 API 密钥本身。
# OpenAI
export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your environment}"
export OPENAI_BASE_URL="https://api.openai.com/v1" # Optional
# Anthropic Claude
export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY in your environment}"
export ANTHROPIC_BASE_URL="https://api.anthropic.com" # Optional
# Google Gemini
export GEMINI_API_KEY="${GEMINI_API_KEY:?Set GEMINI_API_KEY in your environment}"
# Ollama (Local)
export OLLAMA_BASE_URL="http://localhost:11434" # Optional代理配置#
在创建代理时指定模型:
import { Agent } from '@astreus-ai/astreus';
const agent = await Agent.create({
name: 'MyAgent',
model: 'gpt-6-astra', // Explicit selection, not a default change
maxTokens: 2000
});通过 OpenRouter 使用免费托管模型#
OpenRouter 使用现有的 openai 适配器,并非第五个提供方。创建 agent 或 LLM 实例前,请同时设置网关 URL 及其对应密钥。OPENROUTER_API_KEY 是你设置的环境变量,会赋给适配器的 OPENAI_API_KEY。
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_API_KEY="${OPENROUTER_API_KEY:?Set OPENROUTER_API_KEY in your environment}"截至 2026-09-13,OpenRouter 模型目录列出的以下 ID 均为输入和输出 token 价格为零,并标注支持工具调用:
openrouter/freenvidia/nemotron-3.5-lightning:freegoogle/gemma-4-31b-it:freegoogle/gemma-4-26b-a4b-it:free
import { Agent } from '@astreus-ai/astreus';
const agent = await Agent.create({
name: 'HostedFreeAgent',
model: 'openrouter/free',
maxTokens: 1000
});
const response = await agent.ask('Explain how a hash table works.');
console.log(response);免费托管服务有请求速率和可用性限制,并非无限使用。如果免费模型不可用,请处理错误或显式选择另一个免费模型;Astreus 不会自动回退到付费模型。框架的免费许可证不代表托管 API 免费,本地 Ollama 仍需要硬件和电力。
这些带命名空间的 ID 必须使用 OpenRouter 端点。要恢复直连 OpenAI,请同时恢复 OPENAI_BASE_URL=https://api.openai.com/v1 和 OpenAI 签发的密钥。修改基础 URL 会影响使用该适配器实例的所有请求。
无需凭据查询模型#
getModelsByProvider 无需 API 凭据或已认证客户端即可读取框架的本地目录。这不能证明你的账户拥有访问权限,也不能保证托管模型当前可用。
import { getModelsByProvider } from '@astreus-ai/astreus';
const modelIds = getModelsByProvider('openai');
console.log(modelIds);使用示例#
基本 LLM 用法#
import { getLLM } from '@astreus-ai/astreus';
const llm = getLLM();
// Generate response
const response = await llm.generateResponse({
model: 'claude-sonnet-5',
messages: [{ role: 'user', content: 'Explain quantum computing' }],
maxTokens: 1000
});
console.log(response.content);流式响应#
// Stream response in real-time
for await (const chunk of llm.generateStreamResponse({
model: 'gpt-6-astra',
messages: [{ role: 'user', content: 'Write a story about AI' }],
stream: true
})) {
if (!chunk.done) {
process.stdout.write(chunk.content);
}
}函数调用#
const response = await llm.generateResponse({
model: 'gpt-6-astra',
messages: [{ role: 'user', content: 'What\'s the weather in Tokyo?' }],
tools: [{
type: 'function',
function: {
name: 'get_weather',
description: 'Get current weather information',
parameters: {
type: 'object',
properties: {
location: {
type: 'string',
description: 'City name'
}
},
required: ['location']
}
}
}]
});
// Handle tool calls
if (response.toolCalls) {
response.toolCalls.forEach(call => {
console.log(`Tool: ${call.function.name}`);
console.log(`Args: ${call.function.arguments}`);
});
}LLM 选项#
通过以下选项配置 LLM 的行为:
interface LLMRequestOptions {
model: string; // Required: Model identifier
messages: LLMMessage[]; // Required: Conversation history
temperature?: number; // Model-dependent; omit for GPT-6 Astra
maxTokens?: number; // Max output tokens (default: 4096)
stream?: boolean; // Enable streaming responses
systemPrompt?: string; // System instructions
tools?: Tool[]; // Function calling tools
}参数详解#
- temperature:可选,取决于模型。使用 GPT-6 Astra 时请省略;并非所有模型都接受采样参数。
- maxTokens:响应中的最大 token 数(因模型而异)
- stream:为长响应启用实时流式传输
- systemPrompt:设置模型的行为和上下文
- tools:启用函数调用能力
提供方特性#
| 特性 | OpenAI | Claude | Gemini | Ollama |
|---|---|---|---|---|
| 流式传输 | ✅ | ✅ | ✅ | ✅ |
| 函数调用 | ✅ | ✅ | 有限 | 有限 |
| 视觉 | ✅ | ✅ | ✅ | ✅ |
| 嵌入 | ✅ | ❌ | ✅ | ✅ |
| Token 用量统计 | ✅ | ✅ | 有限 | ✅ |
| 自定义 Base URL | ✅ | ✅ | ❌ | ✅ |
| 本地模型 | ❌ | ❌ | ❌ | ✅ |
视觉模型#
每个提供方都支持特定的图像分析模型:
OpenAI 视觉#
gpt-6-astra、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.4-mini、gpt-5.4-nanogpt-4.1、gpt-4.1-mini、gpt-4.1-nano、gpt-4o、gpt-4o-mini、gpt-4-turbo
Claude 视觉#
claude-fable-5-1、claude-opus-5、claude-sonnet-5claude-haiku-4-5-20251001
Gemini 视觉#
gemini-1.5-pro、gemini-1.5-flashgemini-1.0-pro-vision-latest、gemini-pro-vision
Ollama 视觉#
llava、llava:7b、llava:13b、llava:34bllava-llama3、llava-phi3、moondream
嵌入模型#
用于知识库和语义搜索:
OpenAI 嵌入#
text-embedding-3-large(3072 维)text-embedding-3-small(1536 维)text-embedding-ada-002(1536 维)
Gemini 嵌入#
text-embedding-004embedding-001
Ollama 嵌入#
nomic-embed-text、mxbai-embed-largeall-minilm、snowflake-arctic-embed
注意:Claude/Anthropic 不支持嵌入。请使用 OpenAI 或 Gemini 生成嵌入。
其他环境变量#
# Dedicated embedding API keys (optional)
OPENAI_EMBEDDING_API_KEY="your-embedding-key"
OPENAI_EMBEDDING_BASE_URL="https://api.openai.com/v1"
GEMINI_EMBEDDING_API_KEY="your-gemini-embedding-key"
# Dedicated vision API keys (optional)
OPENAI_VISION_API_KEY="your-vision-key"
OPENAI_VISION_BASE_URL="https://api.openai.com/v1"
ANTHROPIC_VISION_API_KEY="your-anthropic-vision-key"
ANTHROPIC_VISION_BASE_URL="https://api.anthropic.com"
GEMINI_VISION_API_KEY="your-gemini-vision-key"模型选择指南#
用于代码生成#
- 最佳:
gpt-6-astra、claude-sonnet-5、deepseek-coder - 快速:
gpt-4o-mini、claude-haiku-4-5-20251001
用于推理任务#
- 最佳:
claude-opus-5、gpt-6-astra、o3 - 均衡:
claude-sonnet-5、gpt-4o
用于创意写作#
- 最佳:
gpt-6-astra、claude-opus-5 - 快速:
gemini-2.5-pro、gpt-4o-mini
用于隐私保护/本地使用#
- 最佳:
deepseek-r1、llama3.3、qwen3 - 代码:
deepseek-coder、codellama