Embedding | Democratizing Data

What I Learned Switching My Blog's Embedding Model for Recommendations, With an LLM as a Research Partner

Sun, 09 Aug 2026 16:52:00 -0700

Intro

This site’s related-article recommendations run on a tool I built myself: , a CLI wrapper around , which enriches Hugo front matter with various metadata.

itself only computes related articles via TF-IDF keyword similarity, but prelims-cli adds embedding-based recommendation on top. It’s built to run on GitHub Actions on every new post: no GPU, limited memory.

I’d been using for Japanese and for English, the lightest models that still gave decent quality. Then , a new small, lightweight embedding model, came out, and I tried it to see whether I could unify the Japanese and English models under one that also covers other languages.

The related articles on this site now run on Bekko a25m. This post covers how I got there, and in particular the trouble I ran into running the experiments with Claude.

How to use it for embedding-based recommendation with prelims-cli

Since prelims-cli v0.0.11, you can use Bekko embedding by setting the multilingual option.

Write a file like the one below as embedding.yaml, and run uvx --python 3.13 'prelims-cli[embedding]' --config embedding.yaml from GitHub Actions.

handlers:
 - target_path: "content/blog"
 processors:
 - permalink_base: "/post"
 type: embedding_recommender
 language: multilingual
 topk: 3
 cache_db: ".prelims_embedding_cache.db"

The story starts with a comparison of the old and new embedding models, done with Claude Opus 5.

First attempt, and why I gave up

These are related articles on my own blog, so there’s no ground truth to evaluate against. I asked Opus 5, and it proposed a proxy metric: tag/category agreement rate. The full definition is in the report below, but roughly: the denominator is the number of top-k recommended articles that carry any tags or categories, and the metric counts how many of those share a tag or category with the source article.

The result was noise-level: the metric’s resolution was ±5–7pt, while the difference between models was only about 2pt. Raising the input length from 2,000 to 8,000 characters improved English quality more than switching models did.

Body length distributions per language

Since this runs in GitHub Actions CI, download time is processing time. Switching to Bekko a25m bumps the model size to 199 MB, well above the 35 MB and 52 MB of the models I’d been using. I concluded the benefit wasn’t worth the cost, and moved on.

The metric was broken

That’s when Opus 5 pointed out that the denominator |P| in the tag/category agreement rate isn’t fixed. It moves with the recommendations themselves. Bekko happened to recommend tagged articles more often, which inflated its denominator and made its agreement rate look worse.

Opus 5 had been noting this growing denominator in the HTML report the whole time. Neither of us, human or LLM, had read it. That’s the irony.

An LLM’s evaluation looks plausible on the surface, but it will commit to a metric without checking the underlying data distribution first.

Two ways to respond to a broken metric

I’d already half-suspected that a tag shared across more than one article was the exception rather than the rule. So I plotted the tag distribution to check.

Tag distribution

Sure enough: in Japanese, 39 of 69 tags/categories appear on only a single article; in English, 19 of 26. Of the 4,465 possible pairs among the 95 tagged Japanese articles, only 212 (4.7%) share a label. There are barely any “correct answers” to measure against.

Tag/category agreement rate simply doesn’t have the coverage to work as an overall metric.

I decided Opus 5 was stuck in a local optimum on this one, so I switched to Fable 5 and asked for a new metric. Fable 5 proposed fixed-pool precision@k, which fixes the denominator problem, plus pairwise AUC. It dropped tag agreement entirely.

But once I’d settled on that and moved back to Opus 5, it kept clinging to the metric it had originally proposed, still reporting agreement between tag agreement rate and the human evaluation I collected later.

Being put to work by Claude

I remembered the advice you hear again and again when evaluating anything in an AI agent context: look at the real data. So I had Claude build me an annotation tool and did the evaluation by hand.

It struck me, working through the evaluation in the browser, how easily coding agents now throw together one-off annotation tools like this.

Annotation tool

I stopped after annotating 162 of the 389 articles with recommendations: enough to confirm that all three top metrics favored the new model, with the difference staying non-negative even at the lower bound of the confidence interval.

Somewhere around then, complaining to Claude about how exhausting the annotation was, I found out it had quietly been running an active learning technique that only shows you the cases where the two models’ recommendations differ. The AI had slipped in an efficient (read: demanding) labeling method, and put me to work without my noticing.

What the human labels actually showed

What I saw in that painful hand-annotation, combined with the LLM’s own observations, tipped me toward adopting the new model.

The LLM’s observations helped too.

For a write-up of a new album by the Real Group (a Swedish jazz a cappella group), a25m surfaces two reviews of earlier albums by the same artist; the old model returned a live announcement for a different artist entirely.

For a review of Utsukushii Kodomo (“Beautiful Children”) by Ira Ishida (a prolific Japanese novelist best known for the Ikebukuro West Gate Park series and the 2003 Naoki Prize winner 4 TEEN), a25m surfaces Akihabara@DEEP and Ai ga Inai Heya (“The Room Without Love”), both by the same author; the old model matched on author only once.

For the report on Kawasaki Ruby Kaigi 01, a25m puts its sister event, Kanagawa Ruby Kaigi, at the top; the old model returned monthly meetup reports instead.

It figured out that Kanagawa Ruby Kaigi and Kawasaki Ruby Kaigi are sister events, which impressed me. It also picked up on overlapping authors and artists, which felt satisfying to see. The two models have different habits, but this one was good enough to adopt.

Going back through my own older posts, I noticed the early ones read like a diary and often ramble across several topics at once. That’s a good reminder of just how hard it is to recommend related articles for posts like that.

Open report in a new tab

Making it work in CI

With Bekko embedding qualitatively confirmed as an improvement, I cleared the remaining technical blockers in parallel:

Cached the model download from Hugging Face in GitHub Actions
Optimized batching so embedding wouldn’t hit the memory limit

With those in place, embedding all 452 articles takes 3 minutes 8 seconds including the model download, or 2 minutes 51 seconds with the cache warm: a realistic runtime. In practice, embeddings are computed incrementally as new articles are added, so it’s even faster day to day.

That’s how I ended up adopting Bekko a25m for related-article recommendation.

Three takeaways

Three things came out of this.

An LLM’s evaluation is surface-level. Go look at the data yourself.
Humans are creatures LLMs can put to work doing active learning.
Opus 5 tends to cling to whatever method it originally proposed, so for ambiguous, open-ended tasks, Fable 5 was the better fit.

1 and 3 weren’t news to me, but 2 was a genuine surprise. I’d always assumed coding agents try to maximize how much they can get out of me as the human in the loop. I didn’t expect one to quietly slip in such a demanding method.

ブログの推薦用軽量embedding modelをBekkoに変えた

Wed, 05 Aug 2026 19:55:00 -0700

前回の話はこちらにあるので見てほしい

今、このブログではBekko a25mで関連記事が出るようになっている。そこに至るまでの経緯を書いていこう。

最新版のレポートはこちら

レポートを別タブで開く

Opus 5が設計する代理指標の罠

正解ラベルのない推薦タスクなため、タグ・カテゴリ一致率という指標をOpus 5が提案した。この代理指標の重大な問題にOpus 5が気づいたため追加調査を行った。

一致率の分母 |P| というのは、推薦された記事に依存して変わるのである。

Bekko a25mは、タグ・カテゴリのついた記事を推薦しやすいという傾向が見られた。なので、再現率が上がり、分母が増えるから一致率が下がるという現象が発生していた。しかも、これをずっとOpus 5はHTMLに補足として書いていたのである！（人もLLMも真面目に読んでいなかった！）

Fable 5への切り替えとアノテーションツール

これを改善するために、Fable 5に切り替え指標を提案してもらった。今回は、分母を固定する固定プール precision@k とペアワイズAUCを使って比較をした（詳細はレポートを見てほしい）。Top 3についてみると、Bekko a25mのほうが同等か良くなっていた。

現行モデル対 bekko-a25m（英語のP@3は結局人手評価では）

しかし、タグ・カテゴリが付与されている記事は限られるし、同じタグがある記事数も限られるということを思い出し、タグの出現頻度分布を見たところ、やはり厳しいだろうとなった。

実際のデータをみないといけないと思い、Claudeに比較とアノテーションのためのツールを作ってもらいブラウザで人手評価をした。ツールでは出力結果に（順位を除いた）差異があったものだけを評価するスタイルになっている。Fableはしれっとactive learningの手法を使ってきたのだ。実は一部出力に対する所見はOpus/Fableにも出してもらっていたが、自分でデータを見ることが大事というのを思い出し初心に帰ったのだ。

アノテーションツール

389記事中162記事を評価したところで打ち切ったのだが、それを元に評価をし直したところ、信頼区間の下限まで見ると自信はないが、top 3の指標の差は全部非負であった。

LLMから得られた所見も役に立った。

The Real Group の新譜紹介 → a25m は同じアーティストの旧譜レビュー2件を並べる。現行は別アーティストのライブ告知を返した。

石田衣良「うつくしい子ども」の書評 → a25m は同じ著者の「アキハバラ＠DEEP」「愛がいない部屋」を並べる。現行は著者一致1件。

川崎Ruby会議01 の開催報告 → a25m は姉妹イベントの神奈川Ruby会議を最上位に。現行は毎月のミートアップ報告を返した。

姉妹イベント、よくわかりましたね。著者やアーティストの重なりも見ており良いのでは、という気持ちになった。癖と言うか傾向の違いはあれど実用に足りうると言えるだろう。

ブログ初期はほぼ日記だったので、雑多なテーマが多くタイトルからは想像できない記事も多かった。

遠回りをしたけど、結局は人手でデータを見るのが大事なのであった。

CIでembeddingする際の技術的なハードルの解決

並行していくつかのGHAのCIで実行するための最適化を行った。

モデルサイズが大きくなってもCIの実行時間を伸ばさないために、HFのモデルキャッシュをGHAでキャッシュする
embedding時にメモリ上限に引っかからないために、バッチングを最適化

これらにより、全452記事のembeddingがモデルDL込で3分8秒（キャッシュ利用時で2分51秒）と現実的な時間で動くことが確認できた。実際には、embedding vectorの計算は記事が追加されるごとに差分で実行されるので、もっと速くなる。

つまり、運用上の懸念点がなくなったのである。

こうして、Bekko a25mによる関連記事推薦が採用される運びとなった。

prelims-cli でBekko a25mを使うには

v0.0.11からBekko a25mを multilingual optionを渡すと使えるようになっている。

詳細はのPRを見てほしいが、設定としては以下のように書くだけである。

 - permalink_base: "/post"
 type: embedding_recommender
 language: multilingual
 topk: 3
 cache_db: ".prelims_embedding_cache.db"

ぜひ、試してみてほしい。感想お待ちしています。

ブログの推薦用軽量embedding modelをBekkoに変えようとして、変えれなかった

Tue, 04 Aug 2026 20:03:00 -0700

このサイトでは、している。prelims-cliはfrontmatterに色々と情報を付加できるをCLIで動くようにしたものである。

実装した当初、embedding modelを使った類似記事推薦をやってみたいと思ったが、当時使ったembedding modelではTF-IDFベースの手法に比べてイマイチな結果しか出なかったため諦めていた。

時は流れ、に「今どきはCPUでもサクサク動く軽量embedding modelがありますよ」と教えられてGitHub Actionsで動くのであった。

ruri-v3とgraniteが軽量だが性能が良いと言うので試してみたら、TF-IDFと比較してもレコメンド結果をざっと目視で見ても悪くない結果だったので採用した。なにより、sudachiの辞書をGHAからダウンロードするよりもembedding modelをダウンロードする方が速いのである。

つい先週、seconさんがという小型モデルをリリースしたという記事を読んだ。これは、ワンチャン日英大統一できないかなー、日英以外もサポートできないかなーと思って、Claude任せに実験をしてみた。三連休の最終日なのに。

それで、出来た実験結果はこちら。

レポートを別タブで開く

簡単に言うと、失敗である。

理由はいくつかあるが

自分のサイトのブログ記事の関連に正解データがない
代理指標として記事のタグ・カテゴリが同じものを推薦出来るかを見たが、タグ・カテゴリが付与されている数も少なかった
そんな指標で測ったので、日英両方とも既存モデルに対して大幅な改善は得られなかった（指標の分解能が±5〜7ptで、比べていた差が2pt前後とおよそ誤差レベル）
むしろ、レコメンドに使う文字列長を伸ばしたほうが、英語は改善した（データをみたら英語のほうが文字数が多い記事が多かった）

記事の文字数頻度分布

定性的にいくつか見比べても悪くはない感じではあったのだが、好みとしても既存モデルの傾向の方が良かったのもある。

「homebrewを移動してiRubyが壊れたときに見直すポイント」 (tags: ruby)
- ruri → 「Pythonの環境構築を自分なりに整理してみる」 (環境構築のトラブル)
- a25m → 「kawasaki.rb #008 を開催しました」 (Ruby)
「新しいPyPIでMarkdownのドキュメントを使う」 (tags: python)
- ruri → 「prelimsを使ってHugoの記事にレコメンドを追加する」 (tags: python)
- a25m → 「mecab-python3を捨ててnatto-pyにしよう」 (tags: nlp)

1個目なんかは、環境構築系という意味では似ているなと感じる。2個目もHugoもMarkdownだしね、というので良いかなと感じた。

こうしたことを鑑みて、日英は既存のモデルを維持することとし、他言語も計測できないのに入れてもなーということで諦めた。評価用の正解データがないと比較できないという当たり前の結果になった。Bekkoは速くて軽いのはとてもよいのだけど、a25mは既存のモデルよりは遅くかつ重かった(199 MB 対 ruri 37 MB / granite 52 MB)し、実験を進めるうちにGHAのcache等の改善もした結果、統一しなくてもいいかなという気持ちになってしまったのもある。