Skip to content

soanseng/vocbuilderAI

BranchesTags

Repository files navigation

VocBuilderAI for Anki

English | 繁體中文

English

VocabBuilderAI is an Anki add-on that enhances vocabulary learning by integrating with multiple LLM providers. It generates comprehensive flashcards including definitions, pronunciations, etymology, synonyms, antonyms, and real-world examples.

Supported LLM Providers

  • OpenAI
  • Groq
  • OpenRouter
  • Custom OpenAI-compatible providers, including LiteLLM

Recommended Models

Model names change quickly, so VocBuilderAI lets you type any chat-completions compatible model supported by your provider.

For the best results in 2026, use a current general-purpose model with strong JSON output and multilingual support. Recommended starting points:

  • OpenAI: use the current small or flagship GPT model for balanced cost and quality.
  • OpenRouter: choose a recent high-quality model with Japanese and Traditional Chinese support.
  • Groq: use its current chat/reasoning model if you prefer faster generation.

Leave the model field blank to use VocBuilderAI's provider default. If Japanese output is incomplete, switch to a stronger multilingual model before raising temperature.

Features

  • Comprehensive vocabulary flashcards
  • Multiple LLM provider support, including custom OpenAI-compatible endpoints
  • Text-to-speech for pronunciation through OpenAI or custom OpenAI-compatible TTS
  • Settings health checks for API, Japanese JSON, and text-to-speech
  • Generation modes for concise, standard, deep, or Japanese-focused cards
  • Safer JSON parsing and config migration for add-on upgrades
  • Short-lived cache for repeated identical generations
  • Customizable decks, card types, and tags
  • Seamless Anki integration

demo

Installation

  1. Download vocbuilderai-*.ankiaddon from the GitHub Releases page.
  2. In Anki, open Tools -> Add-ons -> Install from file.
  3. Select the downloaded .ankiaddon file.
  4. Restart Anki after installing or updating the add-on.
  5. Open Tools -> VocBuilderAI Settings.
  6. Add at least one API key for OpenAI, Groq, OpenRouter, or a custom provider.
  7. Run the built-in health checks before generating cards.

For local development, symlink the add-on files into Anki's add-on directory:

mkdir -p ~/.local/share/Anki2/addons21/voc_builder_ai
ln -sf "$PWD/__init__.py" ~/.local/share/Anki2/addons21/voc_builder_ai/__init__.py
ln -sf "$PWD/prompts.py" ~/.local/share/Anki2/addons21/voc_builder_ai/prompts.py
ln -sf "$PWD/config.json" ~/.local/share/Anki2/addons21/voc_builder_ai/config.json
ln -sf "$PWD/manifest.json" ~/.local/share/Anki2/addons21/voc_builder_ai/manifest.json
ln -sf "$PWD/llm.py" ~/.local/share/Anki2/addons21/voc_builder_ai/llm.py
ln -sf "$PWD/settings.py" ~/.local/share/Anki2/addons21/voc_builder_ai/settings.py
ln -sf "$PWD/parsing.py" ~/.local/share/Anki2/addons21/voc_builder_ai/parsing.py
ln -sf "$PWD/formatters.py" ~/.local/share/Anki2/addons21/voc_builder_ai/formatters.py

Keep meta.json inside the Anki add-on directory. It is user-specific and may contain API keys, so it should not be committed.

Note Type Setup

Create a note type called "vocbuilderAI" with these fields:

  • Vocabulary
  • Detail definition
  • Pronunciations
  • Sound
  • Etymology, Synonyms, and Antonyms
  • Real-world examples

Configuration

Open Tools -> VocBuilderAI Settings and configure these tabs:

  • Generation: choose OpenAI, Groq, OpenRouter, or Custom; choose a generation mode; set model, temperature, max tokens, and cache behavior.
  • API Keys: enter the API key for the provider you want to use.
  • Anki: set the default deck, tag, and note type.
  • Speech: set OpenAI speech or custom OpenAI-compatible TTS, including model, voice, format, and speed.

Generation modes:

  • Concise: shorter cards with fewer examples.
  • Standard: balanced default for daily use.
  • Deep: richer definitions and usage notes.
  • Japanese: Japanese-focused output with stable readings, grammar, and Traditional Chinese translations.

Leave the model field blank to use the provider default.

For the GB10 LiteLLM service, choose custom, set the custom base URL to http://100.102.183.27:4000/v1, and use one of these models:

  • qwen36-fast
  • qwen36-deep
  • qwen36-35b-heretic

Keep Disable Qwen thinking enabled for these models. It sends the vLLM/LiteLLM enable_thinking=false option so the add-on receives final JSON in message.content.

For the GB10 Kokoro TTS service, set Speech -> Provider to custom, set the custom base URL to http://100.102.183.27:8001/v1, and use:

  • Model: speaches-ai/Kokoro-82M-v1.0-ONNX
  • Format: wav
  • Sample rate: 24000
  • Voice: leave blank to choose a live-verified voice automatically. English words use American af_* / am_* voices; Japanese words use jf_* / jm_* voices.

Japanese TTS uses the generated furigana reading when available, so kanji such as 禁煙 are spoken from kana like きんえん instead of leaving pronunciation entirely to the TTS model.

Health Checks

Before generating cards, use these buttons in Tools -> VocBuilderAI Settings:

  • Test API: verifies the selected provider, model, API key, and JSON response.
  • Test Japanese JSON: verifies that Japanese output can be generated and parsed safely.
  • Test TTS: verifies the configured text-to-speech settings.

If a check fails, change the API key, provider, or model before creating cards.

Usage

  1. Open Anki's Add window.
  2. Select the vocbuilderAI note type.
  3. Type the English or Japanese word in the first field.
  4. Click the VocAI button in the editor toolbar.
  5. Review the generated fields.
  6. Click Add to save the note.

For Japanese vocabulary, use the Japanese generation mode if you want more consistent readings, grammar, and Traditional Chinese translations.

screenshot1 screenshot2 screenshot3

Troubleshooting

  • Unsupported parameter: max_tokens: update to the latest add-on version. OpenAI uses max_completion_tokens.
  • Japanese cards are incomplete: run Test Japanese JSON, switch to Japanese mode, or use a stronger multilingual model.
  • The button does not appear: restart Anki after installing or updating the add-on.
  • API errors: verify the selected provider, model name, and API key in settings.
  • No audio: verify the selected speech provider, API key, base URL, model, and run Test TTS.

Traditional Chinese

VocabBuilderAI 是一款 Anki 擴充功能，透過整合多個 LLM 供應商來增強單詞學習體驗。它能自動生成包含定義、發音、詞源、同義詞、反義詞及實際例子的完整記憶卡片。

支援的 LLM 供應商

  • OpenAI
  • Groq
  • OpenRouter
  • 自訂 OpenAI-compatible 供應商，例如 LiteLLM

推薦模型

模型名稱更新很快，所以 VocBuilderAI 不會把模型寫死；你可以填入供應商支援的任何 chat-completions 相容模型。

2026 年建議優先選擇 JSON 輸出穩定、日文與繁體中文能力好的通用模型：

  • OpenAI：使用當前的小型或旗艦 GPT 模型，在成本與品質之間通常最穩。
  • OpenRouter：選擇近期品質高、明確支援日文與繁體中文的模型。
  • Groq：如果你重視速度，可以使用它目前的 chat/reasoning 模型。

Model 欄位留空時，VocBuilderAI 會使用該 provider 的預設模型。如果日文輸出不完整，先換成更強的多語模型，再考慮調高 temperature。

功能特點

  • 全面的單詞記憶卡片
  • 支援多個 LLM 供應商，包含自訂 OpenAI-compatible endpoint
  • 透過 OpenAI 或自訂 OpenAI-compatible TTS 產生文字轉語音發音
  • 設定頁可測試 API、日文 JSON 與文字轉語音
  • 可選擇簡潔、標準、深入或日文優先的生成模式
  • 更穩定的 JSON 解析與升級設定 migration
  • 對重複的相同生成請求提供短期快取
  • 可自訂牌組、卡片類型和標籤
  • 無縫整合 Anki

安裝方式

  1. 從 GitHub Releases 頁面下載 vocbuilderai-*.ankiaddon。
  2. 在 Anki 打開 Tools -> Add-ons -> Install from file。
  3. 選擇下載好的 .ankiaddon 檔案。
  4. 安裝或更新 add-on 後重開 Anki。
  5. 打開 Tools -> VocBuilderAI Settings。
  6. 至少填入一組 OpenAI、Groq、OpenRouter 或自訂 provider API key。
  7. 先跑內建健康檢查，再開始產生卡片。

本機開發時，可以把專案檔案 symlink 到 Anki add-on 目錄：

mkdir -p ~/.local/share/Anki2/addons21/voc_builder_ai
ln -sf "$PWD/__init__.py" ~/.local/share/Anki2/addons21/voc_builder_ai/__init__.py
ln -sf "$PWD/prompts.py" ~/.local/share/Anki2/addons21/voc_builder_ai/prompts.py
ln -sf "$PWD/config.json" ~/.local/share/Anki2/addons21/voc_builder_ai/config.json
ln -sf "$PWD/manifest.json" ~/.local/share/Anki2/addons21/voc_builder_ai/manifest.json
ln -sf "$PWD/llm.py" ~/.local/share/Anki2/addons21/voc_builder_ai/llm.py
ln -sf "$PWD/settings.py" ~/.local/share/Anki2/addons21/voc_builder_ai/settings.py
ln -sf "$PWD/parsing.py" ~/.local/share/Anki2/addons21/voc_builder_ai/parsing.py
ln -sf "$PWD/formatters.py" ~/.local/share/Anki2/addons21/voc_builder_ai/formatters.py

meta.json 請留在 Anki add-on 目錄裡。它是使用者本機設定，可能包含 API key，不要 commit 進 git。

筆記類型設定

建立名為 "vocbuilderAI" 的筆記類型，包含以下欄位：

  • Vocabulary
  • Detail definition
  • Pronunciations
  • Sound
  • Etymology, Synonyms and Antonyms
  • Real-world examples

設定選項

打開 Tools -> VocBuilderAI Settings 後設定這幾個分頁：

  • Generation：選擇 OpenAI、Groq、OpenRouter 或 Custom；設定生成模式、model、temperature、max tokens 和快取。
  • API Keys：填入你要使用的 provider API key。
  • Anki：設定預設 deck、tag 和 note type。
  • Speech：設定 OpenAI 或自訂 OpenAI-compatible TTS，包含 model、voice、format 和 speed。

生成模式：

  • Concise：較短的卡片，例句較少。
  • Standard：日常使用的平衡預設值。
  • Deep：更完整的定義、用法和補充說明。
  • Japanese：日文優先，強化讀音、文法、例句與繁中翻譯穩定性。

Model 欄位留空時，會使用 provider 的預設模型。

GB10 LiteLLM 可選 custom，custom base URL 設成 http://100.102.183.27:4000/v1，model 可用：

  • qwen36-fast
  • qwen36-deep
  • qwen36-35b-heretic

這幾個模型建議保持 Disable Qwen thinking 開啟。它會送出 vLLM/LiteLLM 的 enable_thinking=false 選項，讓 add-on 可以在 message.content 收到最終 JSON。

GB10 Kokoro TTS 可在 Speech -> Provider 選 custom，custom base URL 設成 http://100.102.183.27:8001/v1，並使用：

  • Model：speaches-ai/Kokoro-82M-v1.0-ONNX
  • Format：wav
  • Sample rate：24000
  • Voice：留空會自動選 live-verified voice。英文使用 American af_* / am_* voice；日文使用 jf_* / jm_* voice。

日文 TTS 會優先使用生成出的 furigana 讀音；例如 禁煙 會用 きんえん 送進 TTS，避免只丟漢字時被模型誤讀。

健康檢查

開始產生卡片前，建議在 Tools -> VocBuilderAI Settings 先測：

  • Test API：確認目前 provider、model、API key 和 JSON 回應可用。
  • Test Japanese JSON：確認日文輸出能產生且可以安全解析。
  • Test TTS：確認目前文字轉語音設定可用。

如果檢查失敗，先更換 API key、provider 或 model，再產生卡片。

使用方法

  1. 打開 Anki 的 Add 視窗。
  2. 選擇 vocbuilderAI note type。
  3. 在第一個欄位輸入英文或日文單字。
  4. 點 editor toolbar 裡的 VocAI 按鈕。
  5. 檢查自動生成的欄位內容。
  6. 點 Add 儲存卡片。

如果主要產生日文卡片，建議使用 Japanese 生成模式，讀音、文法和繁中翻譯會比較穩定。

疑難排解

  • Unsupported parameter: max_tokens：請更新到最新版 add-on。OpenAI 現在使用 max_completion_tokens。
  • 日文卡片內容不完整：先跑 Test Japanese JSON，切到 Japanese 模式，或換成更強的多語模型。
  • 看不到按鈕：安裝或更新 add-on 後請重開 Anki。
  • API 錯誤：確認 settings 裡的 provider、model name 和 API key。
  • 沒有語音：確認 speech provider、API key、base URL、model，並執行 Test TTS。

Support | 支援

For support, questions, or feature requests, please visit our GitHub repository. 如需支援、問題或功能請求，請訪問我們的 GitHub 專案頁面.

About

VocBuilderAI is an Anki add-on designed to enhance vocabulary learning by leveraging OpenAI's GPT-3.5 Turbo and Whisper APIs. It allows users to generate detailed notes for new vocabulary words, complete with definitions, pronunciations, etymologies, synonyms, antonyms, and real-world examples.

Resources

Readme
Activity

Stars

3 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases 6

VocBuilderAI 1.2 Latest
May 1, 2026
+ 5 releases

Packages

 
 
 

Contributors

Languages