このページは GitHub の文書 から作っています。

cse API リファレンス 🐸

cse 0.2.0 の全機能の一覧です。説明はすべて、実際のコード(src/cse/__init__.py と src/cse/_engine.py)の動きに合わせています。

• Frog — 🐸 本体
• 学習と予測 — learn / predict / top / probabilities / generate
• 中身をのぞく — scores / explain / show / edges
• 保存と読み込み — save / load
• END — 系列の終わり
• 設定(Config)の一覧 — Frog(設定名=値) で変えられる全23項目
• エラーの一覧

Frog

cse.Frog(**overrides)

🐸 を1匹つくります。設定を変えたいときは Frog(temperature=2.0) のように名前で渡します(全項目は設定の一覧)。

戻り値: Frog

属性 | 名前 | 説明 | |---|---| | frog.config | 今の設定(CSEConfig)。frog.config.temperature のように読める |

メモ - 作っても、あなたのプログラムの乱数(random / numpy.random)の状態は変わりません。 - 同じ Frog を複数のスレッドから同時に使っても安全です(学習と予測は1つずつ順番に処理されます)。

from cse import Frog
frog = Frog()                          # 既定の設定
hot = Frog(temperature=2.0)            # 温度だけ変える
print(frog.config.refractory_steps)    # -> 0

学習と予測

learn

frog.learn(data, epochs=3) -> Frog

系列を覚えます。自分自身を返すので Frog().learn(...).predict(...) のようにつなげられます。

data の渡し方(predict と同じ考え方): | 渡し方 | 例 | 意味 | |---|---|---| | 文字列1つ | "右右下右右下" | 1本の系列。1文字が1記号 | | リスト1つ | ["正常", "温度上昇", "停止"] | 1本の系列。1要素が1記号(「停止」は分かれない) | | リストのリスト | [["右", "右", "下"], ["正常", "停止"]] | 何本もの系列 |

• 記号には文字列のほか、整数・小数・True/False・None なども使えます(保存できるのはこの5種類)。
• 各系列の最後には、自動で <END>(終わり)が学習されます。
• 注意: weight_decay(既定 0.9995)は学習の1ステップごとに全部の結びつきにかかるので、たくさん学習すると古い記憶が少しずつ薄れます。

predict

frog.predict(prefix=()) -> 記号 または END

prefix の次に一番来そうな記号を1つ返します。prefix を空にすると「最初の記号」を予測します。

top

frog.top(prefix=(), k=3) -> [(記号, 確率), ...]

確率の高い順に k 個返します。

probabilities

frog.probabilities(prefix=()) -> {記号: 確率}

次に来る記号の確率をすべて返します(確率が 0 の記号は含まれません)。合計は 1 です(<START>・<UNK> を除いて割り直しています)。

確率の作られ方: 点数(→scores)の上位 top_k_edges 個だけを、probability_mode(softmax なら温度 temperature)で確率に変えます。点数がプラスの候補が1つもないときは END が確率 1 になります。

frog = Frog().learn([["右", "右", "下"] * 5])
frog.predict(["右", "右"])          # -> '下'
frog.top(["右", "右"], k=2)         # -> [('下', 0.777...), ('右', 0.222...)]

generate

frog.generate(prefix=(), n=20, *, greedy=False, seed=None) -> 文字列 または [記号, ...]

prefix の続きを最大 n 個つくります。END が選ばれたらそこで止まります(END 自体は返しません)。

• 1歩ずつ、それまでの列 prefix + ここまでの生成 で probabilities を計算し、その確率で次の記号を1つ選びます。だから途中のどの1歩も frog.show(prefix + ここまでの生成) でのぞけます。
• greedy=True: 毎回いちばん確率の高い記号を選びます(毎回同じ結果、各歩は predict と同じ)。
• greedy=False(既定): 確率どおりにくじを引きます。seed を決めると毎回同じ結果になります。くじは Frog 専用の乱数(random.Random(seed))で引くので、プログラム全体の random の状態は変わりません。
• prefix が文字列なら文字列を、リストならリストを返します(prefix 自体は含みません)。
• n が 0 以上の整数でないと ValueError。覚えていない記号を渡すと ValueError。

frog = Frog().learn([["右", "右", "下"]] * 3)
frog.generate(["右"], greedy=True)        # -> ['右', '下']
frog.generate(["右"], seed=1)             # くじ。seed が同じなら毎回同じ
Frog().learn("あいうえお").generate("あ", n=3, greedy=True)   # -> 'いうえ'

中身をのぞく

scores

frog.scores(prefix=()) -> {記号: 点数}

確率に変える前の生の点数を、高い順に返します(プラスのものだけ)。Top-p などのサンプラーを自分で作る材料になります。

explain

frog.explain(prefix=(), k=5) -> [dict, ...]

候補ごとに、点数が「どこから来たか」を返します(点数の高い順に k 個)。

保証: 内訳の合計がエンジン自身の点数とビット単位で一致することを、呼ぶたびに確認しています。ずれたら RuntimeError で止まります(説明が実際の計算とずれることはありません)。

show

frog.show(prefix=(), k=5) -> None

explain の結果を表で表示します。

Frog(refractory_steps=2).learn([["右", "右", "下"] * 5]).show(["右", "右", "下"])
# 🐸 ['右', '右', '下'] の次の候補
# 候補            直接      履歴      並び      痕跡      合計点      確率
# <END>      0.298   0.000   0.200   0.000    0.498   1.000
# 右          1.186   0.000   0.800   0.000    0.000   0.000  ← 不応期で消された

edges

frog.edges(token, k=10) -> [(記号, 強さ), ...]

その記号から出ている「直接のつながり」を、強い順に k 個返します(何を覚えたか)。

保存と読み込み

save

frog.save(path) -> None

覚えたことをファイルに保存します。中身は JSON と数値の配列だけの zip です(pickle は使いません。人の 🐸 を読み込んでも安全です)。

load

Frog.load(path) -> Frog

save したファイルから 🐸 を読み込みます。読み込んだ 🐸 は、予測も続きの学習も、保存する前とビット単位で同じになります。読み込みで、あなたの乱数の状態は変わりません。

frog.save("my_frog.cse")
frog = Frog.load("my_frog.cse")

END

cse.END

「ここで系列が終わる」を表す特別な目印です。表示は <END>。あなたの記号(文字列 "<END>" を含む)とはぶつかりません。

if frog.predict(prefix) is END:
    print("ここで終わりそう")

設定(Config)の一覧

Frog(設定名=値) で変えられます。「Frog の既定」は Frog() で作ったときの値、「エンジンの既定」はエンジン本体の値です(Frog は5項目だけ変えています)。

予測のしかた(点数 → 確率)

文脈の記憶

学習のしかた

活性の動き

その他

エラーの一覧