龙石

lodestone.extrafemi.com 互联网档案馆的存檔,存档日期2013-12-02: 互动地走过它的工作.

调用 AI 模型, 这样当一个模型被撤回、 慢或 速率受限时, 您的工具会继续工作 .

免费模特来去去。 一个硬编码的模型id在不发出警告的情况下会中断,一个慢模型可以使用你的整个时间限制,"429"可以指需要四个不同消息的四种不同的东西. Lodestone处理这些,所以每个工具都不用.

• 自行替换已退出的模型. 你的列表是偏好。 与OpenRouter的活版目录核对,任何已经走掉的模型都会被换成现在的同一种.
• 保持时间预算. 每个模型都得到一块. 一个缓慢或失败的模型会被跳过到下一个,所以一个函数从不以无法读取的错误来点击它的网关限制.
• 倒倒倒过供养. OpenRouter的免费模型,然后是付费模型,然后是Anthropic或Google在自己的钥匙上.
• 用简单的语言解释失败. 每日限制,每分钟限制,繁忙的上游提供商,坏键和慢模型都是不同的错误,有不同的建议.
• 检查答案. json() 跳过一个答案无效的模型 JSON 或者没有通过验证器.
• 带好自己的钥匙. 一个呼叫器的键取代了平台的键并允许支付回落,而不触及平台的预算.
• 无依取相. 平面 fetch. 节点20+.

使用

import { anthropic, createLodestone, explain } from '@extrafemi-ai/lodestone';

const ai = createLodestone({
  openrouter: { apiKey: process.env.OPENROUTER_API_KEY },
  fallbacks: [
    { provider: anthropic(), apiKey: process.env.ANTHROPIC_API_KEY!, models: ['claude-haiku-5-5'] },
  ],
  profiles: {
    'extract-job': { tier: 'fast', maxTokens: 1500 },
    'write-cv': { tier: 'strong', maxTokens: 3500, temperature: 0.4 },
  },
});

try {
  const { data } = await ai.json<Job>({ task: 'extract-job', prompt, validate: isJob });
} catch (err) {
  // A message you can show a person.
  return explain(err, { product: 'MyApp', settingsHint: 'in Settings' });
}

validate 是您所写的护卫类型。 或者通过一个计划,任何与 safeParse (例如Zod)和 data 它是返回的 :

const Job = z.object({ title: z.string(), remote: z.boolean().default(false) });
const { data } = await ai.json({ task: 'extract-job', prompt, schema: Job }); // data: { title: string; remote: boolean }

import { anthropic, google, openrouter, mock } from '@extrafemi-ai/lodestone' 为提供适配器.

等级

fast (摘录、分类), strong (书面、判决)和 vision (读取相. 电话会选一个 task 配置图或 tier和用途 vision 当信件包含一个图像时.

选择供货商和模特儿route(中文(简体) )

梯级是用于工具 不关心哪个模型答案。 选择自己的供应商和每个请求的模型(付费模式、客户自己的钥匙)的工具通过a route 相反:这些步骤的正确性,直到一个答案.

await ai.complete({
  system, messages, maxTokens: 900,
  route: [
    { provider: 'anthropic', model: 'claude-sonnet-5-5', apiKey: customerKey },
    { provider: 'openrouter', model: 'anthropic/claude-sonnet-5.5', apiKey: backupKey },
  ],
});

没有键的一步被跳过 。 一个路由跳过模型列表和目录,将温度留给提供者,除非您设置一个,并且仍然得到时间预算,打出故障和使用. detail.providerMessage 错误中包含提供者自己的消息。 替换或添加提供者适配器到 providers 选项,例如 providers: { openrouter: openrouter({ lowReasoning: false }) }。 。 。 .

将客户自己的密钥从任何倒置步骤中保留出:仅从他们的密钥中构建出路径.

你自己的钥匙

通过客户的 OpenRouter 密钥为 apiKey 在电话中。 它取代了平台的密钥,允许支付回落,并且从未被存储. 这个平台 fallbacks 为: 没有 使用客户自己的钥匙的电话(他们携带平台的钱),除非是倒计时 allowWithCallerKey401、402或403失败的尝试不计入实时数据,因为他们对模型一无所知.

阶段

每一个电话,顺序, 直到一个回答:

1. OpenRouter用于分级的免费模型(当前,按目录).
2. 一个付费的OpenRouter模型,只有当呼叫者提供了自己的钥匙或者您设定 allowPaid没有信用 OpenRouter 拒绝 什么都没有用.
3. 每个 fallbacks 提供商,有自己的钥匙.

当后期存在时,自由模型会得到一个短转(默认情况下总共9 s),所以总是会留有时间的. 整个电话都留在里面 budgetMs (默认为24 s,低于30 s 网关限制).

保持目录新鲜

给它某地保存目录(任何能够通过密钥获得并设定JSON的事物;默认是内存). 包括Netlify Blobs、Cloudflare KV、Upstash(和Vercel KV)和Deno KV的适配器,参见 文件/仓库运行 checkModels() 每日一次:

const ai = createLodestone({ store: netlifyBlobsStore(getStore('lodestone')), /* ... */ });

// daily
const { ok, withdrawn, shortTiers } = await ai.checkModels();

withdrawn 列出已消失的首选模型。 这是无害的,他们已经被替换了. ok 只有在目录不能被读取时,或者一个级被留有少于两个真实模型时,才会是虚假的. 没有每日运行,请求找到一天多的被保存目录就可以在背景中刷新.

不值得等待的自由模型(paidFirst(中文(简体) )

自由模型可以下行数小时(有速率限制,或持接通开通45秒而永不接通). 在平台的钥匙上, openrouter: { paidFirst: true } 只在支付模式失败或支出限额达到时,先尝试支付模式和免费模式,所以请求不会被不会回答的自由模式所减缓. 打电话者自己的钥匙不受影响:付费型号是他们的钱,所以他们的免费型号仍然名列前茅. 每个模型都设定了理由 openrouter({ reasoning: (model) => ... }),因为模型不同:一个人想着千个符号,除非被告知不要(测量:将其关闭一半的得分时间,10 s到5 s,有相同的答案),另一个拒绝用推理来运行.

不等待一个模式 下 (断路器)

自由模型在暴发中失败:有收率限制,被卡住,或者什么都不回答. 没有记忆,每个请求都为同样的死模型再次付费. createHealth() 记得:

import { createHealth } from '@extrafemi-ai/lodestone';
const health = createHealth({ store });   // the same store as the catalogue: every serverless function shares it
const ai = createLodestone({ /* ... */, health });

一个最后三次尝试(在10分钟之内)都失败的模型被跳过,所以下一个请求直接到一个起作用的模型. 每两分钟一次尝试看它是否恢复,一次成功再次关闭. 一个超时,一个速率限制,一个服务器出错和一个无法使用的答案算作失败;一个被拒绝的密钥或缺失的信用(401,402,403)对模型一言不发,从不做. 如果每个自由模型都往下看,而一个有报酬的模型可以追随,自由模型就会被完全跳过;如果什么也不能追随,他们仍然被尝试,因为尝试比不回答更好. health.snapshot() 列出它所看到的 健康页面.

限制平台的开支

const spend = createSpendLimit({ store, dailyUsd: 2, monthlyUsd: 30 });
const ai = createLodestone({ /* ... */, spend });

allow 在花费平台资金的每次尝试(平台钥匙上的付费模型和倒置供应商)之前都会被询问,a false 表示该模型没有被使用. record 被告知每一次这种呼叫的费用:提供商在给出一个(OpenRouter确实提供)时自己的数字,否则就是模型目录价格的估计数。 免费模特儿和打电话者自己的钥匙(他们的钱,不是你的)也从未经过. 当限制停止每个付费选项时,错误是 kind: 'budget'A级 record 永远不能失败.

createSpendLimit 使用一个 拿着 每项付款的尝试,只要是允许的,而且计数与限额不符,因此在计算出任何费用之前,同时提出的同时提出的各种要求都不可能全部通过支票。 持仓以实际成本换回答案并归还(release当尝试失败时。 你可以自己写 { allow, record, release? };每个收到一个 id 命名尝试.

每人一份

const spend = createSpendLimit({ store, dailyUsd: 20, perCaller: { dailyUsd: 0.10, monthlyUsd: 1 } });
await ai.complete({ prompt, caller: user.id });

上面的限制是每个人的一池,所以一个重型用户可以全部使用. perCaller 每天和每月给每个来电者各自一份 在每个呼叫中指定呼叫者caller,用户ID或IP地址;只存储散列). 没有呼叫者的呼叫只被扣在游泳池,所以总是通过一个. 免费的模特儿一文不值 也永远不用分钱.

当有人过份时 电话就失效了 kind: 'budget' 财务报告和审定财务报表 detail.scope: 'caller' (单位:千美元)'app' 当整个游泳池耗尽的时候 explain() 每一个字都不同,所以你的应用程序可以说"你用过自己的股份,加上自己的钥匙来继续". spend.callerReport(caller) 返回它们已经使用和可能使用的内容,用于“今日0.10美元的0.04美元”显示.

一个人可以降低自己的份额,永远不要提高:通过 spendCap: { dailyUsd: 0.05 } 他们的呼声 perCaller 适用.

盖上一个人的钥匙

当有人带来了自己的"开路特"(OpenRouter)钥匙时,支出是他们的,而"洛德斯通"并不限制. 这就是默认:没有限制,没有计算. 如果他们想要一个安全网来对付一个圈子或窃听器, 就让他们设置一个,然后把他们的电话传过去:

await ai.complete({ prompt, caller: user.id, apiKey: theirKey, spendCap: { dailyUsd: 2 } });

然后,他们付费拨打的钥匙被算入他们自己的一个分类账中,这个分类账从来不碰你的,然后按他们选择的号码停下来(注:detail.scope: 'own-key') (中文(简体) ). 您的应用程序存储设置; Lodestone 保存计数 .

也设定密钥本身的限制 . OpenRouter 键有它自己的信用限度, 这是它真正维持的。 Lodestone的计数是最佳的:它只看到通过这个应用程序打来的电话,而有一个普通的得到/设置的商店有两个功能在同一时刻回答同一个人,每个功能可以抓住另一个没有看见的. 告诉人们在提供者的钥匙上设置一个限制,并将洛德斯通的盖子当作第二行.

spendCap 需要一个 caller 和限制 createSpendLimit()没有他们,电话就会发出 TypeError 而不是悄悄地无视别人要求的限制.

一人清空预算(rateLimit(中文(简体) )

限花是每个人的一壶。 给每个打电话者自己的津贴,并点出每个打电话者的名号:

const ai = createLodestone({ /* ... */, rateLimit: { limiter: createRateLimiter({ store, max: 20, windowMs: 3_600_000 }), whenOver: 'free-only' } });
await ai.complete({ prompt, caller: userId ?? clientIp });

过他们的津贴,一个打电话的人得到 kind: 'throttled' (单位:千美元)'reject',默认)或仅自由模型('free-only') (中文(简体) ). 只有散列的呼叫器被存储. 见 文件/保护预算 究竟什么是准确的,什么是大致的.

供应商,不依赖一家

OpenRouter是默认的,但一个提供者的出故障不应该停止你的工具. 给洛德斯通其他人 fallbacks每个都有自己的钥匙 任何使用 OpenAI 聊天API 的服务 openaiCompatible(),而且Lodestone的预设已对照:

fallbacks: [
  { provider: requesty(), apiKey: process.env.REQUESTY_API_KEY!, models: ['bedrock/claude-haiku-5-5'], discover: { fill: { maxPromptUsdPerMTok: 1, maxCompletionUsdPerMTok: 5 }, max: 3 } },
  { provider: groq(), apiKey: process.env.GROQ_API_KEY!, models: ['llama-3.3-70b-versatile'], free: true },
]

模特身份是每个服务自己的 见 实例/多提供者.ts。 。 。 .

保持生命力的模型列表 以及短小的

• 过时或关闭. 日报 checkModels() 保存每个提供者当前目录。 一个不再列出提供者的模型被删除;一个在一周内到期的模型被排除在外(OpenRouter出版);一个正在失败的模型被断路器跳过。 没有人编辑列表 .
• 新车型. discover: { fill } 从提供商自己的目录上上一个短列表,其中模型在限价范围内("免费"是受信任的实验室的限值为0). 对于OpenRouter的自由模型来说,这本身就发生了.

谷歌自愈

fallbacks: [{ provider: google(), apiKey: process.env.GOOGLE_API_KEY!, models: ['gemini-2.0-flash'], discover: { replaceRetired: true } }]

Google的列表没有生命周期域,因此这与Anthropic的作品不同. 列表中不再包含的模型默认会从链被丢出. 与 discover: { replaceRetired: true } 它被替换为最新的模式 同一行,从编号读取(flash, (中文(简体) ), flash-lite, (中文(简体) ), pro),并按版本编号排序: gemini-2.0-flash 改为最高 gemini-N-flash。它从不跨行,从不选择预览或日期复制,每次互换都由 checkModels() 下级 providers.google. 一个Google模型仍然列出,但不再服务,没有事先注意到. 呼叫失败,接下来的倒计时被尝试. 与Anthropic一样,它是选入的,因为替换者可能花费更多或回答不同,而支出限制对此没有价格. 已经检查过的内容:逻辑通过假答测试;没有呼叫真正的终点.

人类自愈

fallbacks: [{ provider: anthropic(), apiKey: process.env.ANTHROPIC_API_KEY!, models: ['claude-sonnet-4-20250514'], discover: { replaceRetired: true } }]

Anthropic出版的每个模型在其生命中的位置(active, (中文(简体) ), deprecated, (中文(简体) ), retired),当它退休时,它属于哪行(haiku, (中文(简体) ), sonnet, (中文(简体) ), opus(......) (中文(简体) ). Lodestone 读了这个列表

• 默认 一个退休的身份证,或一周内退休的身份证,被从链子上扔出,所以一个叫法不再浪费了对一个能回答404的模型的尝试. 没有什么能取代它.
• 与 discover: { replaceRetired: true } 一个已经消失的名牌模型被换成了最新的 活动 联合国 同一行,在列表的同一位置。 它从不跨行(Sonnet从不取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取 trust 策略接受,对于图像只使用读取图像的调用。 如果该行没有电流,或者Anthropic不再列出ID(所以其行是未知的),则没有交换.
• 永不寂灭. checkModels() 返回,在 providers.anthropic, (中文(简体) ), replaced: [{ from, to, reason }] 财务报告和审定财务报表 unreplaced: [{ id, reason, note }]每一个答案都说出是哪个模型生产的 处理a replaced 作为更新列表的提示.
• 为什么它是选择进入. 替换成本可能更高,回答不同,或者需要其他设置,而Anthropic的列表没有价格,因此支出限额无法估计一个被互换的模型成本. 保持状态比保持原样更重要的时候再打开它.

已检查内容:逻辑通过假答来测试,场名沿用了Anthropic的Models API参考. 尚未调用真实的终点, 文档本身的示例对认证头和 API 版本( Lodestone sends) 不一致 x-api-key 财务报告和审定财务报表 2023-06-01,如同留言一样). 如果列表无法读取,则您所命名的模型会按原样使用.

• 别再等了. 发现从不延长请求的行走 一个背景池(每层可达8个)排名,下行的模型被过滤出,请求最多尝试了3个. 当一个失败时,下一个最佳人选将取而代之,用于后期请求,所以添加模型会增加选择,而不是延迟.
• 默认安全. 只有当其出版商被列入信托名单时,才使用已发现的模型; trust 还要一个块列表,拒绝一个提供商说接受过训练的模型,或者让提示时间太长 private: true 同一办法也适用于一次呼叫(见下文)。 没有关于主机模型的脆弱性数据库,因此没有声称: 警卫 准确的是什么和没有检查.

私人电话private: true(中文(简体) )

不得保留或培训(简历、医疗票据)。 确切地说,它的作用是:

• OpenRouter 被告知只使用不保持或训练在提示上的提供者(data_collection: deny) (中文(简体) ).
• 只有当它自己的模型清单说该模型没有经过训练时,才使用倒置提供者(请公布这一点), 或者说 你保证过 privacy: 'no-training' 倒计时 供养者,无出版而未担保者被忽略了,即使你设置不 trust 政策。 洛德斯通无法看清提供商以即时的方式做什么,除非提供商说.
• 答案从不读取或写入缓存.
• 它的失败不计算在一个模型上(那些提供商可以遵守规则,这丝毫不说模型).
• 明确 route 是你们自己选择的供养者,是按规定经过的.

取消

const controller = new AbortController();
req.on('close', () => controller.abort());           // the person left the page
await ai.complete({ prompt, signal: controller.signal });   // throws a LodestoneError of kind 'aborted'

它运行的地方

Lodeston只使用网络标准API,没有依赖性. CI对Cloudflare工人的20号、22号和24号节点进行相同的烟雾检查(在 workerd,没有节点兼容旗),在德诺和邦. 见 文件/运行时间 以它所表现的和所不显示的.

蟒

python/ 持有核心的 Python 端口:故障、时间预算、断路器、支出持有量、每个呼叫器的费率限制、私人通话和 explain(),仅使用标准库。 它为α,尚未读取提供者模型列表或支持图像. 见 蟒蛇/README.md。 。 。 .

还没有

• 流来. complete() 财务报告和审定财务报表 json() 等待整个答案。 流出需要决定一个半衰期的模型;可能的规则是在第一个标志之前就失败.
• 工具调用 (模型可以调用的职能),和 嵌入或语音洛德斯通是一发短信 和JSON今天打电话.

由测量决定顺序

一个记分卡(一个测量结果的JSON小文件)可以把最出色的模型放在你这种任务上,而Lodestone可以以同样的格式发布自己的活性成功率和速度. 奈亚·埃瓦尔 以这种方式出版豪萨、伊格博和约鲁巴的翻译和演讲质量。 它被选入,每个任务, 并且只有改变顺序模型 尝试。 见 文件/计分卡.md。 。 。 .

缓存

过 cacheKey 用于纯可重复的任务(例如工作页的散列),答案保存在存储中,再用于 cacheTtlMs (默认为一日). 密钥必须代表整个输入;作为一个保障,一个答案也被绑在系统即时,消息和分级的指纹上,所以一个过于粗糙的密钥会给一个错,从不给另一个输入的答案. 失败永远不会被缓存,和 已标记的呼叫 private 从未从缓存读取或写入。 。 。 .

观察它

onAttempt 与提供商、模型、相位、结果、状态和时间进行每次模式尝试后,就称为“模式尝试”。 它从未收到提示或答案。 洛德斯通在任何地方都不记录提示或回答.

错误

complete() 财务报告和审定财务报表 json() 丢出一个 LodestoneError 谁 kind 这是其中之一 auth, (中文(简体) ), rate_limit, (中文(简体) ), slow, (中文(简体) ), credit, (中文(简体) ), withdrawn, (中文(简体) ), unavailable, (中文(简体) ), bad_output, (中文(简体) ), aborted, (中文(简体) ), budget, (中文(简体) ), throttled, (中文(简体) ), not_configured 或者说 other。 。 。 . detail 带有 HTTP 状态, 对于费率限制, 它属于哪种. explain(err, { product, settingsHint }) 把其中任何一个都变成一个人的讯息.

开发

npm install
npm test
npm run build

npm run smoke 财务报告和审定财务报表 npm run smoke:workers 运行交叉运行时间检查。 释放:起伏 version 内 package.json,然后按下标签(git tag v0.1.0 && git push --tags) (中文(简体) ). 发布工作流程测试,用出处构建并发布到npm. 它使用 npm 信任的出版, 所以没有符号可以保存 : npm 信任此寄存器和 release.yml 直接(设置在 npmjs.com 上的软件包设置下).

许可证

麻省理工学院