@godspeedai/cognate-provider-openai-compatible

中文文档
0.10.0发布于 2026/11/16Apache-2.0ES Module构建来源已验证近 30 天下载 3746

ModelProvider for OpenAI-compatible chat completion endpoints (llama.cpp, vLLM, Ollama's /v1, hosted APIs) over fetch; no SDK.

原始使用文档
文档目录7 节
  1. Installation
  2. Quick start
  3. What is mapped
  4. Kernel component
  5. Limitations
  6. Related packages
  7. License

@godspeedai/cognate-provider-openai-compatible

A Cognate model provider for any OpenAI-compatible chat completions endpoint — llama.cpp, vLLM, Ollama's /v1, LM Studio, or hosted APIs — over plain fetch. No vendor SDK.

When to use this package: your app needs a real model and the server speaks the OpenAI /chat/completions wire format. For deterministic scripted answers in tests, use @godspeedai/cognate-provider-local instead.

Installation

bun add @godspeedai/cognate-provider-openai-compatible

Requires Bun >= 1.4.0 (it uses the platform fetch, AbortSignal, and web streams). The SDK ships Bun-native TypeScript source, so add @types/bun and @types/node as dev dependencies when typechecking your project.

Quick start

import { openAICompatible } from "@godspeedai/cognate-provider-openai-compatible";

const provider = openAICompatible({
  id: "gpt-4o-mini", // provider id becomes `openai-compatible:gpt-4o-mini`
  baseURL: process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1",
  model: "gpt-4o-mini",
  apiKey: () => process.env.OPENAI_API_KEY ?? "", // read per request, never stored
  timeoutMs: 60_000,
});

const response = await provider.generate({
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.message.content);
console.log(response.usage); // { inputTokens, outputTokens } when the server reports usage

// Streaming: text deltas and tool-call deltas, then a final `done` delta
// carrying the assembled full response.
for await (const delta of provider.stream({ messages: [{ role: "user", content: "Hello!" }] })) {
  if (delta.type === "text") process.stdout.write(delta.text);
}

Point baseURL at any compatible server, for example http://localhost:11434/v1 for Ollama or your llama.cpp/vLLM route. The provider posts to <baseURL>/chat/completions.

What is mapped

  • Messages and tools become the OpenAI wire shape: tools as { type: "function", function: { name, description, parameters } }, assistant tool calls with JSON-stringified arguments, responseFormat.schema as json_schema (or json_object without a schema), plus max_tokens and temperature.
  • Streaming parses SSE data: lines (tolerant of chunk boundaries), accumulates tool calls whose id, name, and arguments arrive split across chunks, and yields ordered deltas followed by tool_call entries and a done delta with the assembled response.
  • Errors become typed ModelProviderError kinds: unauthorized (401/403), rate_limited (429), invalid_request (other 4xx), unavailable (5xx, network errors, timeouts), cancelled (caller abort), and malformed_response (unparseable bodies).

The apiKey function is called per request and its value is never stored, logged, or included in an error message or in the capability contract the provider publishes.

Kernel component

modelComponent(provider) wraps a provider as a kernel Component publishing the model.generate capability, so a runtime can select and invoke it like any other capability:

import { modelComponent } from "@godspeedai/cognate-provider-openai-compatible";

const component = modelComponent(provider);
// pass it in the runtime's `components` list

Limitations

  • Chat completions only: no embeddings, files, audio, or assistant-state APIs.
  • Feature flags default to stream/tool_use/structured_output true, multimodal_input false, context_limit 8192. Override features to match what your server actually supports, or eligibility checks will trust flags the server may not honor.
  • Structured output depends on the server honoring response_format; the provider delivers whatever the server returns.
  • Tool call arguments must be valid JSON on the wire; a server that streams malformed arguments surfaces malformed_response.

License

Apache-2.0

版本与发布记录

@godspeedai/cognate-provider-openai-compatible 共发布 20 个版本,首次发布于 2026/10/09;过去 12 个月发布了 20 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.10.0latest2026/11/16今天
0.9.22026/11/152 天前
0.9.12026/11/143 天前
0.9.02026/11/0610 天前
0.8.02026/10/2720 天前
0.7.12026/10/2523 天前

关于 @godspeedai/cognate-provider-openai-compatible 的常见问题

@godspeedai/cognate-provider-openai-compatible 是什么?

ModelProvider for OpenAI-compatible chat completion endpoints (llama.cpp, vLLM, Ollama's /v1, hosted APIs) over fetch; no SDK.

如何安装 @godspeedai/cognate-provider-openai-compatible?

在项目目录运行 npm install @godspeedai/cognate-provider-openai-compatible,或使用 pnpm add / yarn add / bun add。

@godspeedai/cognate-provider-openai-compatible 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/godspeedai__cognate-provider-openai-compatible 是否存在。

@godspeedai/cognate-provider-openai-compatible 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@godspeedai/cognate-provider-openai-compatible 可以商用吗?

@godspeedai/cognate-provider-openai-compatible 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@godspeedai/cognate-provider-openai-compatible 的下载量有多少?

根据 npm 官方下载统计,@godspeedai/cognate-provider-openai-compatible 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,746 次,日均约 125 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@godspeedai/cognate-provider-openai-compatible 还在维护吗?

最新版本 0.10.0 发布于 2026/11/16(今天);至今共发布 20 个版本,其中过去 12 个月发布了 20 个;首次发布于 2026/10/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。