DemensDeum

Notes

Language

俄罗斯 OpenCode 人工智能提供商

Written by

demensdeum

in

OpenCode 是一个开放的编程代理，可以直接在终端中工作：读取项目文件、编辑代码、运行命令和测试、搜索存储库并使用 git。它的优势在于它不依赖于一个模型提供商，并且可以连接数十个提供商。

GigaChat 是 Sber 的大型语言模型。它不在 OpenCode 提供程序的就绪列表中，但这不是问题：OpenCode 通过 Vercel AI SDK 包连接任意提供程序。对于 GigaChat，有一个包 gigachat-ai-sdk-provider，它负责 OAuth 授权和更新访问令牌。一个单独的细微差别是数字发展部证书：没有它们，Node 不信任 GigaChat 服务器，并且请求会因证书验证错误而失败。

在这篇文章中，我将描述如何获取密钥、安装证书并将 GigaChat 连接到 OpenCode。

你需要什么

要工作，你需要三样东西：

  • 已安装 OpenCode。如果尚未安装代理，我会在有关 OpenCode 和 DeepSeek 的单独说明中讨论安装过程。
  • GigaChat 帐户。在 GigaChat Studio 中注册并获得授权密钥 – 您需要 Sber ID 才能登录。
  • 现代终端。WezTerm、Alacritty、Ghostty、Kitty 或任何其他终端都可以。

GigaChat 授权密钥

密钥是在您的 GigaChat Studio 个人帐户中创建的。转到developers.sber.ru/studio，登录并在GigaChat API部分创建一个项目。在项目设置中，有一个包含授权数据的块：从那里复制的行是一个现成的 Base64 授权密钥。正是这个被替换到环境变量中，而不是单独的客户端秘密对。

与键一起指定范围 – 访问区域：

  • GIGACHAT_API_PERS – 适用于个人。
  • GIGACHAT_API_B2B – 适用于个体企业家和法人实体。
  • GIGACHAT_API_CORP – 公司访问权限。

显示的密钥值应立即保存：以后不会再次显示，如有必要，必须发出新的密钥值。

了解这条线是什么很重要。授权密钥不是单独的密钥，而是一对已经以 Base64 编码的 client_id:client_secret。 gigachat-js 库将此标头替换为 OAuth 请求：

Authorization: Basic ваш_ключ_авторизации

作为响应，JWE 访问令牌的生命周期约为半小时，然后库会自动更新它。该包本身会检查该值是否类似于 base64，并在该变量意外包含“原始”客户端机密时发出警告。因此，需要将帐户中现成的base64字符串传输到config和环境变量中，而不是单独传输client_id和client_secret对。

数字发展部的证书

GigaChat API 使用 NCA 数字发展部颁发的证书。标准可信根存储没有它们，因此当尝试获取访问令牌时，请求失败并显示如下错误：

self-signed certificate in certificate chain

证书可以安装在操作系统级别 – 然后它们将受到浏览器和系统实用程序的信任。但 OpenCode 运行在 Node 和 Bun 上，因此直接在 NODE_EXTRA_CA_CERTS 变量中指定证书文件更安全、更容易。下载根证书和颁发者证书并将它们放入一个 PEM 文件中：

curl -s https://gu-st.ru/content/lending/russian_trusted_root_ca_pem.crt -o russian_trusted_root_ca_pem.crt
curl -s https://gu-st.ru/content/lending/russian_trusted_sub_ca_pem.crt -o russian_trusted_sub_ca_pem.crt
cat russian_trusted_root_ca_pem.crt russian_trusted_sub_ca_pem.crt > russian_trusted_ca_bundle.pem

该文件可以放置在方便的位置，并且可以在启动代理时指定其完整路径。

这里有一个问题。下载的文件使用 CRLF 换行符，并且根证书没有尾随换行符。因此，普通的猫将第一个证书的末尾和第二个证书的开头连接成一行：

-----END CERTIFICATE----------BEGIN CERTIFICATE-----

LibreSSL – 以及 macOS 上的 openssl 系统，让我提醒一下，正是 LibreSSL – 不接受这样的文件并返回错误：

PEM routines:CRYPTO_internal:bad end line

这意味着仅猫是不够的。每个证书必须首先通过 openssl 运行：它将其重新编码为带有 LF 换行符和最终换行符的规范 PEM，然后才合并：

openssl x509 -in russian_trusted_root_ca_pem.crt -out russian_trusted_root_ca.pem
openssl x509 -in russian_trusted_sub_ca_pem.crt -out russian_trusted_sub_ca.pem
cat russian_trusted_root_ca.pem russian_trusted_sub_ca.pem > russian_trusted_ca_bundle.pem

您可以检查文件是否正在被读取，如下所示：

openssl x509 -in russian_trusted_ca_bundle.pem -noout -subject

如果证书取自其他来源并采用 DER 或 PKCS#7 格式，它们也可以重新编码为 PEM：

openssl x509 -in cert.crt -inform DER -outform PEM -out cert.pem
openssl pkcs7 -print_certs -in bundle.p7b -out cert.pem

连接到 OpenCode

该提供程序在 opencode.jsonc 配置文件中进行描述。 OpenCode 本身将下载并连接 npm 字段中指定的 npm 包，找到其中的 createGigaChat 工厂并将选项传递给它。通过 API 中的标识符列出模型就足够了。

该文件可以放置在两个地方：

  • 全局 – ~/.config/opencode/opencode.jsonc。这些设置适用于所有用户项目。
  • 在项目中 – 项目根目录中的 opencode.jsonc。此配置具有更高的优先级，并且可以安全地提交到 git。

两个文件使用相同的方案并组合在一起：项目文件仅与匹配密钥的全局文件重叠，其余设置将被保存。还支持 .jsonc 扩展名。如果仅某些存储库需要 GigaChat，则将提供程序保留在项目配置中而不是全局配置中会更方便。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gigachat": {
      "npm": "gigachat-ai-sdk-provider",
      "name": "GigaChat",
      "models": {
        "GigaChat-2-Max": { "name": "GigaChat 2 Max" },
        "GigaChat-2-Pro": { "name": "GigaChat 2 Pro" },
        "GigaChat-2": { "name": "GigaChat 2 Lite" },
        "GigaChat": { "name": "GigaChat" }
      }
    }
  }
}

此处列出了可提供个人密钥的型号。如果您有一个针对个体企业家或有权访问 GigaChat 3 的法人实体的项目，请将 models 方法中的必要标识符添加到 models 块中。

更方便的做法是不将密钥本身存储在文件中，而是将其传递给环境变量：gigachat-js 包会自动读取它。范围值也可以设置为变量。剩下的就是设置证书的路径并启动代理：

export GIGACHAT_CREDENTIALS=ваш_ключ_авторизации
export GIGACHAT_SCOPE=GIGACHAT_API_PERS
export NODE_EXTRA_CA_CERTS=/путь/к/russian_trusted_ca_bundle.pem
opencode

此选项也很好，因为秘密不会最终存储在本地 auth.json 存储中：它仅存在于进程的环境中。这对于 CI 和一次性启动来说更加方便。

模型

可用模型集取决于范围键。个人密钥 (GIGACHAT_API_PERS) 可用于 GigaChat 和 GigaChat 2 系列：

  • GigaChat – 基本模型。
  • GigaChat-2 – 用于日常任务的快速且轻量级的模型，在界面中显示为 Lite。
  • GigaChat-2-Pro – 针对资源密集型任务的改进模型。
  • GigaChat-2-Max 是使用个人密钥可用的最强大的功能。

GigaChat 3 系列（GigaChat-3-Ultra、GigaChat-3-Pro、GigaChat3.5-432B-A28B-Reasoning 等开放模型）在控制台目录中可见，但不可用于个人密钥：它需要个人企业家项目或具有 GIGACHAT_API_B2B 或 GIGACHAT_API_CORP 范围的法人实体以及合适的费率。在个人密钥上，这样的模型会响应错误：

{"status":404,"message":"No such model"}

您可以通过查询模型列表来检查密钥实际输出的内容：

curl -H "Authorization: Bearer <токен_доступа>" https://gigachat.devices.sberbank.ru/api/v1/models

还有两点。 API 中的模型 ID 与显示的名称不匹配 – 轻型模型称为 GigaChat-2，而不是 GigaChat-2-Lite。并且控制台中的目录不会显示与您的密钥可用的内容相同的内容，因此您应该关注模型方法的响应，而不是价格列表。

在界面中，使用以下命令打开模型列表：

/models

对于存储库中的日常工作 – 浏览文件、较小的编辑、运行测试 – GigaChat-2 已经足够了。对于复杂的任务和设计，切换到 Pro 或 Max 是有意义的。

项目中首次启动

转到项目目录并启动代理：

cd ваш_проект
opencode

第一步是初始化代理：

/init

OpenCode 将分析项目结构并创建一个文件 AGENTS.md – 代理指令。该文件值得提交到 git：它可以帮助代理理解项目中采用的约定和模式。

替代方案：本地代理

如果由于某种原因您不想使用 npm 提供程序，本地代理会给出相同的结果。 GigaChat 团队拥有官方 gpt2giga – FastAPI 服务，可将 OpenAI、Anthropic 和 Gemini 格式的请求转换为 GigaChat API 并更新访问令牌本身。它在端口 8090 上本地引发，之后通过 @ai-sdk/openai-company 包在 OpenCode 中配置常规 OpenAI 兼容提供程序，其基地址为 http://localhost:8090/v1。此路径的缺点是您还需要在 OpenCode 旁边保留一个正在运行的 Python 服务。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gigachat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "GigaChat (proxy)",
      "options": {
        "baseURL": "http://localhost:8090/v1"
      },
      "models": {
        "GigaChat-2-Max": { "name": "GigaChat 2 Max" }
      }
    }
  }
}

DeepSeek 和其他模型（通过 Cloud.ru）

GigaChat API 本身没有 DeepSeek 模型：只有 GigaChat 系列和用于嵌入的模型。如果您需要 OpenCode 中的 DeepSeek，但需要通过俄罗斯云网关，则 Cloud.ru 的 Foundation Models 服务比较合适。它使用 OpenAI 兼容协议提供模型，因此使用标准 @ai-sdk/openai-company 包进行连接。

例如，在 Cloud.ru 基础模型目录中，有以下模型：

deepseek-ai/DeepSeek-V4.1-Flash
deepseek-ai/DeepSeek-V4-Flash
deepseek-ai/DeepSeek-V4-Pro

密钥在 Cloud.ru 控制台中颁发：“用户”部分，“服务帐户”选项卡。我们创建一个项目级服务帐户，然后在其凭据中使用 Foundation Models 服务创建一个 API 密钥。密钥显示一次，我们保存它。

opencode.json 中的提供程序配置如下所示：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cloudru": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Cloud.ru Foundation Models",
      "options": {
        "baseURL": "https://foundation-models.api.cloud.ru/v1",
        "apiKey": "{env:CLOUDRU_API_KEY}"
      },
      "models": {
        "deepseek-ai/DeepSeek-V4.1-Flash": { "name": "DeepSeek V4.1 Flash", "limit": { "context": 1048576, "output": 1048576 } },
        "deepseek-ai/DeepSeek-V4-Flash": { "name": "DeepSeek V4 Flash", "limit": { "context": 1048576, "output": 1048576 } },
        "deepseek-ai/DeepSeek-V4-Pro": { "name": "DeepSeek V4 Pro", "limit": { "context": 1048576, "output": 1048576 } }
      }
    }
  }
}

我们将密钥传递给环境变量：

export CLOUDRU_API_KEY=ваш_ключ_cloudru
opencode

这里不需要数字发展部证书：api.cloud.ru 域具有常规 TLS，与 GigaChat 不同。但值得监控项目的平衡。如果帐户为零，则授权通过，请求将随计费响应一起丢弃：

{"message":"Not enough money"}

这不是配置错误，而是您需要在 Cloud.ru 控制台中更新项目的信号。

需要注意什么

首次设置时最常遇到的几个实际问题：

  • 证书验证错误。有关链中自签名证书的消息意味着未选取 NODE_EXTRA_CA_CERTS 变量。检查文件的路径、代理是否在同一环境中运行以及文件本身：如果使用 cat 合并两个证书时，它们的末尾位于同一行，LibreSSL 将返回错误的结束行，并且需要通过 openssl 重建捆绑包，如有关证书的部分中所示。
  • 错误 401。 一般来说，这是一个不正确的授权密钥或不匹配的范围 – 对于个人，您需要 GIGACHAT_API_PERS。
  • 错误 404，并显示文本“没有这样的模型”。这不是连接失败，而是无法访问特定模型。从配置中删除它或将其替换为可用的配置。在像 GigaChat 404: Unknown error 这样的消息中，同样的 GigaChat 响应是罪魁祸首 – 提供程序根本无法解析错误正文。
  • 成本。OpenCode 不需要订阅：您在花费代币时直接向 GigaChat 付款，因此长时间会话的价格是可以预测的。
  • 模型质量。对于复杂的架构任务，不同类别的模型有所不同，因此对于设计来说，采用更强大的模型并将例程交给更快的模型是有意义的。

链接

https://opencode.ai/
https://opencode.ai/docs/providers/
https://developers.sber.ru/studio/
https://developers.sber.ru/docs/ru/gigachat/guides/main
https://github.com/nyddle/gigachat-ai-sdk-provider
https://github.com/ai-forever/gpt2giga
https://cloud.ru/docs/foundation-models/ug/topics/quickstart

来源

https://opencode.ai/docs/providers/#custom-provider
https://developers.sber.ru/docs/ru/gigachat/certificates
https://developers.sber.ru/docs/ru/gigachat/models/main
https://developers.sber.ru/docs/ru/gigachat/guides/selecting-a-model
https://github.com/nyddle/gigachat-ai-sdk-provider
https://github.com/ai-forever/gpt2giga
https://cloud.ru/docs/foundation-models/ug/topics/quickstart
https://cloud.ru/docs/foundation-models/ug/topics/overview__available__models

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts

DemensDeum
Powered by  GDPR Cookie Compliance (opens in a new tab)
Privacy Overview

This website uses cookies so that we can provide you with the best user experience possible. Cookie information is stored in your browser and performs functions such as recognising you when you return to our website and helping our team to understand which sections of the website you find most interesting and useful.