黑毛到白毛的攻城獅之路

Vespa groups 的使用時機

2026-08-10T22:26:18.088+08:00

很久沒寫部落格了，因為現在在 AI 時代，其實有點覺得找不到寫部落格的動機 XD…不過因為去年到今年持續使用 Vespa 的 groups 時，遇到一些問題而因此跟 Vespa 團隊有不少討論，簡單紀錄一下這些經驗和結論。然後先承認這篇是我寫完簡單的草稿之後給 AI 幫我補細節的，因為我懶得再自己去找範例跟畫表格 XDDD。

Vespa 的 flat mode、group mode 與 scaling 策略

首先是什麼時候應該使用 flat mode，什麼時候應該使用 group mode？

大體上的經驗是，content node 開到 50 個以上時，就應該開始考慮轉成 group mode。group mode 下，每個 group 都保存一份完整資料，而 Vespa 會把一個 query 只送到其中一個 group，再由該 group 內的 content nodes 平行處理。因此，增加 group 可以增加 query throughput，同時避免每個 query 都要 fan-out 到整個 cluster。

再來，使用 group mode 時，應該要：

依 group 數量 scaling
依 group 內 node 數量 scaling
兩者同時啟用

簡要答案是：看情況，但幾乎沒有理由使用 (3)，大致上是 (1) 或 (2) 選一個。

不使用 (3) 的主要原因是難以預測。當 scaling 行為觸發時，增加 group 或增加 group 內 node，都有可能改善當前資源壓力；但很難預測 Vespa 最後會採用哪一種拓撲。因此 query latency、資料重分布量，以及成本的變化都會比較不穩定。

以下範例以 Vespa Cloud 的 services.xml 為例：

策略	Vespa 設定範例	Scaling 時發生什麼事	對 query latency 的影響	對 memory / 資料容量的影響	適合情境
(1) 只依 group 數量 scaling	`<nodes groups="[2, 4]" group-size="8">`	每個 group 固定 8 台 node；Vespa 在 2 到 4 個 group 之間擴縮。	最穩定。新增一個 group 後，每個 query 仍只會查固定的 8 台 node。	現有 group 的 node memory 使用率不會下降，因為每個新 group 都必須保存完整資料；只是整體 memory 與成本會隨 group 數增加。	query 流量變動大、希望擴縮後 latency 行為可預期的情境。
(2) 只依 group 內 node 數量 scaling	`<nodes groups="3" group-size="[8, 32]">`	group 數固定為 3；總 node 數在 8 到 32 台之間變動，因此每個 group 的 node 數會增加或減少。	有些微影響。group 變大時，query 要 fan-out 給更多 content node；scale-out 幅度越大，影響通常也越明顯。	每個 group 的資料被分到更多 node，單一 node 的 memory、disk 與 CPU 壓力都會下降。	query 流量相對穩定，但資料量、index size 或 memory 壓力會持續變動的情境。
(3) 同時依 group 與 group 內 node 數量 scaling	`<nodes groups="[2, 4]" group-size="[8, 32]">`	Vespa 可以同時改變 group 數與每組 node 數。	最難預測：可能是增加 group，也可能是增加每組 node，兩者對 latency 的效果不同。	同樣難預測：可能新增完整資料副本，也可能只是把既有 group 的資料分散到更多 node。	通常不建議。除非已經理解 autoscaler 的實際行為，並可接受 topology 變動的不確定性。

(1) 的 group 組成是固定的，scaling 是增加或減少 group。因為每個 group 都要包含完整資料，所以增減 group 不會降低既有 node 的 memory 使用率；scale-out 的本質是增加一整份資料副本。不過 query 每次面對的 node 數不變，因此 latency 表現最穩定。

(2) 的 group 個數不變，但增加或減少 group 內的 node 個數。Vespa 會把 query 送給被選中的 group 內所有 content node，所以 group 內 node 越多，query 的 fan-out 對象也越多，對 latency 會有些微影響。不過相對地，資料會分散到更多 node，單一 node 的 memory 與 disk 壓力會下降，因此比較適合查詢流量穩定、但資料量變動大的情境。

最後一個實務上的提醒：如果最終確實需要同時改變 group 數與 group size，建議拆成兩次調整，中間等資料重分布完成。這樣比較容易維持完整 query coverage，也比較容易觀察每次 topology 變動帶來的影響。

參考資料：

[筆記] Apache Spark 的 AQE 造成的 Execution Plan 過大

2025-10-20T11:50:00.004+08:00

Ref: https://medium.com/towards-data-engineering/apache-spark-wtf-i-love-it-when-a-plan-comes-together-part-iii-296a44d323dd

[筆記] VS Code 的 Copilot 對話紀錄位置

2025-07-31T22:06:00.006+08:00

今天突然遇到對話歷史紀錄消失的問題，本來以為是對話紀錄太老了被刪除了，不過實際上或許是 VS Code Insider 更新的緣故，導致舊的格式可能讀不到之類的….？總之實際上對話紀錄還在，只是 VS Code Insider 上看不到。

想找回對話紀錄的話，以 Mac 來說，可以去 ~/Library/Application Support/Code - Insiders/User/workspaceStorage/{uuid}/chatSessions 資料夾裡面找，對話紀錄會以 JSON 形式存在那裡。

ECS Fargate 在 non-root 環境下使用 MountPoints

2025-04-21T21:02:00.002+08:00

在 Fargate 預設使用 MountPoints 去利用 ephemeral storage 作為兩個 container 之間分享資源的手段時，可能會遇到如果 container 本身是 non-root user 的話，會導致無法寫入 ephemeral storage 的問題。

這是因為 Fargate 的 ephemeral storage 預設只能夠被 root 寫入。而這個問題，目前能夠做的 workaround 如下，基本上是在 Dockerfile 中，將要作為 ephemeral storage 的目錄設定為 VOLUME，就可以保留路徑內的資料不會被 bind mount 遮蓋，而且也會有權限可以讀寫該路徑。

USER node
RUN touch /var/log/exported/examplefile
VOLUME ["/var/log/exported"]

詳情可以參考 GitHub issue。

Spark 新手筆記（二）：在本機打開 Spark History Server 查看 event logs

2025-02-22T22:20:00.005+08:00

這篇要紀錄如何使用 Spark History Server。因為我們專案在使用 AWS EMR 時，是可以在 AWS 上打開 Spark History Server，但一方面打開要開很久，而且一段時間沒去存取的話，Server 又會自動被關掉，另一方面在 AWS 開的 History Server 常遇到一些奇怪的問題，但好像又沒辦法對它做什麼調整，所以就在想說有沒有辦法把資料下載到本機，在本機開 Spark History Server 呢？結論來說，是可以的，這篇就會紀錄在本機要如何使用 Spark History Server。

選擇合適的 Spark 版本

首先在開始之前，先提一下我試了一個下午的結果，目前 Spark 最新版的 3.5.x 因為底下會用到 Jackson 2.15.x，這個版本的 Jackson 引入了 JSON 長度的限制，而且現在這個限制似乎是無法調整的。Github 上有對應的 issue 與 PR 想要改成沒有限制長度，但寫這篇文章的現在，這個 PR 還沒有被 merge。回到問題本身，具體來說，這個問題會導致長度超過 20M 的 Spark event logs 沒辦法被 History Server 讀取，會拋出類似以下的錯誤訊息：

URI:    /history/application_1739961940470_0001/1/jobs/
STATUS:    500
MESSAGE:    com.fasterxml.jackson.core.exc.StreamConstraintsException: String length (20054016) exceeds the maximum length (20000000)
SERVLET:    org.apache.spark.deploy.history.HistoryServer$$anon$1-2787de58
CAUSED BY:    com.fasterxml.jackson.core.exc.StreamConstraintsException: String length (20054016) exceeds the maximum length (20000000)

而以本機來說，最簡單又快速的解法，就是去下載 Spark 3.4.x 或更早以前的版本，3.4.x 版的 Spark 使用的 Jackson 版本是 2.14.x，就可以避開這個問題了。

設定相關的 History Server 參數

這個步驟可能不一定是必要的，只是因為 History Server 都有預設設定，但預設設定不見得符合需求，所以適度調整一下會比較方便。

首先，History Server 預設會去 file://tmp/event-logs 資料夾尋找 event logs，但如果不想把 event logs 放在暫存資料夾，可以指定一個別的資料夾讓 History Server 去讀取。作法是把 Spark 資料夾中的 conf/spark-defaults.conf.template 更名成 conf/spark-defaults.conf，然後寫上以下的設定：

spark.history.fs.logDirectory=/YOUR/PREFERRED/PATH

另外 Spark History Server 預設使用的記憶體是 1GB，但如果你會讀非常龐大的 event logs 的話，1GB 很有可能會不夠用，這時打開 History Server 後，可能會在 job 頁面看到類似以下的錯誤訊息：

URI:    /history/application_1739961940470_0001/1/jobs/
STATUS:    500
MESSAGE:    org.sparkproject.guava.util.concurrent.ExecutionError: java.lang.OutOfMemoryError: Java heap space
SERVLET:    org.apache.spark.deploy.history.HistoryServer$$anon$1-27b71f50
CAUSED BY:    org.sparkproject.guava.util.concurrent.ExecutionError: java.lang.OutOfMemoryError: Java heap space
CAUSED BY:    java.lang.OutOfMemoryError: Java heap space

這時要增加可用的記憶體，可以去修改 daemon memory 設定，這個設定是放在另一個檔案，所以要先把 conf/spark-env.sh.template 改名成 conf/spark-env.sh，然後在裡面加上以下的設定，把記憶體改成你想要的用量，這邊的例子是改成 4GB。

SPARK_DAEMON_MEMORY="4g"

啟動與關閉 Spark History Server

在本機啟動 History Server，只要去 Spark 資料夾內的 sbin 資料夾裡執行 start-history-server 即可。執行後如果想看 History Server 有沒有預期的反應，可以去查看 /logs 資料夾裡的 log。

以下是執行的範例：

$ cd spark-3.4.4-bin-hadoop3-scala2.13/sbin/
$ ./start-history-server
starting org.apache.spark.deploy.history.HistoryServer, logging to /mnt/d/spark-3.4.4-bin-hadoop3-scala2.13/logs/spark-jimwayne-org.apache.spark.deploy.history.HistoryServer-1-JW-HOMEPC-12700.out
$ tail -f ../logs/spark-jimwayne-org.apache.spark.deploy.history.HistoryServer-1-JW-HOMEPC-12700.out
25/02/22 22:12:56 INFO SecurityManager: Changing view acls groups to:
25/02/22 22:12:56 INFO SecurityManager: Changing modify acls groups to:
25/02/22 22:12:56 INFO SecurityManager: SecurityManager: authentication disabled; ui acls disabled; users with view permissions: jimwayne; groups with view permissions: EMPTY; users with modify permissions: jimwayne; groups with modify permissions: EMPTY
25/02/22 22:12:56 INFO FsHistoryProvider: History server ui acls disabled; users with admin permissions: ; groups with admin permissions:
25/02/22 22:12:56 INFO JettyUtils: Start Jetty 0.0.0.0:18080 for HistoryServerUI
25/02/22 22:12:56 INFO Utils: Successfully started service 'HistoryServerUI' on port 18080.
25/02/22 22:12:56 INFO HistoryServer: Bound HistoryServer to 0.0.0.0, and started at http://10.255.255.254:18080
25/02/22 22:12:56 INFO FsHistoryProvider: Parsing file:/mnt/d/spark-events/application_1739961940470_0001_1 for listing data...
25/02/22 22:12:57 INFO FsHistoryProvider: Looking for end event; skipping 1919341552 bytes from file:/mnt/d/spark-events/application_1739961940470_0001_1...
25/02/22 22:12:57 INFO FsHistoryProvider: Finished parsing file:/mnt/d/spark-events/application_1739961940470_0001_1

上面可以從 log 看出，啟動成功後，Spark History Server 會開在 http://localhost:18080，並且會自動開始讀取 spark.history.fs.logDirectory 設定的資料夾裡面的 event logs 檔案。因為我已經在裡面放了一個從 EMR 下載下來並解壓縮的檔案，所以它可以掃到並開始解析這個檔案。

最後，用瀏覽器打開 http://localhost:18080 就可以進入 Spark History Server 查看了。要看在雲端或其他環境執行的狀況，就去把那邊的 Spark event logs 下載回來，放在 spark.history.fs.logDirectory 指定的目錄即可。

PS. 目前測試 History Server 好像無法接受 ZIP，雖然 ChatGPT 跟我說 Spark History Server 可以支援壓縮檔…。

到這裡，就可以避開文章最開始提到 AWS EMR 的 Spark History Server 常常打不開的各種奇怪問題了！雖然說第一步還是得先打開 EMR 上的 Spark History Server，並且上去下載 event logs 啦 😆

Spark 新手筆記（一）：在本機安裝 Spark 並執行一個簡單的 Scala 程式

2025-02-19T01:09:00.005+08:00

最近開始參與 Spark 的專案，所以有空的時候會開始做一些 Spark 新手筆記 😆。我的環境是 Windows 11，不過實際上在不同環境的作法應該沒有差太多的感覺，但或許會有一些小地方有微妙的不同就是了。因為我自己的電腦是 Windows 11，但平常比較習慣在 Linux-based 的環境開發，所以實際上文章中會紀錄的東西，大體上會是 Windows 11 + WSL2 的狀況，指令原則上我都是在 WSL2 的 Ubuntu 裡執行的。

Spark 環境準備

首先，根據 Spark 官方文件來看，Spark 本身不需要安裝，只需要下載並執行相應的指令即可。因此主要需要準備的環境是 Java、Maven，並且下載 Spark。其中 Java 跟 Maven 怎麼安裝，我就直接略過了，這裡簡單說明我目前的環境：

Java: 21.0.6+7-Ubuntu-124.04.1
Maven: 3.8.8

在 Spark 官方網站下載 Spark 時，因為目前的最新版是 3.5.4，因此我是選擇以下的選項下載的：

Spark: 3.5.4
Package Type: Pre-built for Apache Hadoop 3.3 and later (Scala 2.13)

其中 Package Type 其實我目前也不太確定效果是什麼，但因為我的範例專案會用 Scala，因此就選了名字有 Scala 的 🙃。

準備範例專案

新手的第一件事就是先弄個 Hello World，不過 Spark 印 Hello World 好像有點弱，所以我弄了一個比 Hello World 複雜一滴滴的範例專案，順便也簡單試了一下 Spark 與 Scala 的寫法。

git clone git@github.com:jimwayneyeh/example-spark-scala.git

接著因為要把打包的 JAR 丟去給 Spark 執行，所以我們需要把這個專案打包成 JAR。

cd example-spark-scala
mvn clean package

打包出來的檔案會在 ./target/example-spark-scala-1.0-SNAPSHOT.jar，這個路徑先記住，等等會用到。在那之前先來看一下這個範例專案裡寫了什麼。首先可以先看 tw.jimwayneyeh.example.spark_scala.App 這個類別，它的內容如下：

object App {

  def main(args: Array[String]): Unit = {
    println("Hello World!")

    val spark = SparkSession.builder().appName("exmaple app").getOrCreate()
    val customerDf =
      spark.read.options(Map("header" -> "true")).csv("customers-100.csv")
    println(s"Count: ${customerDf.count()}")

    spark.stop()
  }

}

因為程式碼很短，就不一一贅述了，簡單來說就是先建立一個 SparkSession，讀取專案根目錄的 customers-100.csv 檔，這個 CSV 檔是從 sample-csv-files 下載的範例 CSV 檔。CSV 讀取進來變成 data frame，指定它是有標頭的，然後算出這個 data frame 的個數並印出來。

讀取檔案的部份要特別注意的是，這裡給的路徑是相對於專案目錄的路徑，但檔案並非放在 src/main/resources 資料夾內。我詢問 ChatGPT 時，ChatGPT 回答說 Spark 正常運作時，資料都是從外部路徑帶進來的，所以一般來說 Spark 程式並不會讀取 JAR 裡面的資源。這個理由聽起來是感覺蠻合理的，畢竟會特地用 Spark 執行的運算，資料量應該都不會小，也不會有人想把資料放進 JAR 裡吧 😆。

另外也看一下一個最簡單的 Spark 專案，如果用 Maven 打包的話，需要什麼東西。POM 裡面只需要以下的 dependencies 即可。

<dependency>
    <groupId>org.scala-lang</groupId>
    <artifactId>scala-library</artifactId>
    <version>${scala.version}</version>
</dependency>
<dependency> <!-- Spark dependency -->
    <groupId>org.apache.spark</groupId>
    <artifactId>spark-sql_${scala.binary.version}</artifactId>
    <version>3.5.4</version>
    <scope>provided</scope>
</dependency>

其中可以特別注意到，Spark 的 dependency 的 scope 會是 provided，這應該是因為實際執行時，JAR 會跑在 Spark 上，所以 Spark dependencies 應該在執行環境上都有。

在 Spark 執行

範例專案的 JAR 準備好以後，回到前面下載好的 Spark 壓縮檔，把它解壓縮後進入 /bin 資料夾，並且執行以下的 spark-submit 指令，就可以啟動一個本機的 Spark 環境執行剛剛的範例專案了。

./spark-submit --class "tw.jimwayneyeh.example.spark_scala.App" --master local /PATH/TO/PROJECT/target/example-spark-scala-1.0-SNAPSHOT.jar

等了一下之後，就可以看到 console 輸出的 Spark logs 了。這裡我貼了很長，是因為順便想要紀錄它的執行過程，之後想要分析它的內容。不過現階段重要的是 log 當中格式沒有日期的那兩行，因為程式碼是用 println() 來輸出的，所以會忽略 logging 格式直接在 console 印出只有 message 的 log。可以看出它算出了 data frame 裡面有 100 筆資料。

Hello World!
Count: 100

以下則是紀錄一下 log 當中印出跟 App.scala 有關的部份，這些 log 就是實際在排程並執行範例程式時的過程了。

25/02/19 00:38:51 INFO SparkContext: Created broadcast 0 from csv at App.scala:14
25/02/19 00:38:51 INFO FileSourceScanExec: Planning scan with bin packing, max size: 4211559 bytes, open cost is considered as scanning 4194304 bytes.
25/02/19 00:38:52 INFO SparkContext: Starting job: csv at App.scala:14
25/02/19 00:38:52 INFO DAGScheduler: Got job 0 (csv at App.scala:14) with 1 output partitions
25/02/19 00:38:52 INFO DAGScheduler: Final stage: ResultStage 0 (csv at App.scala:14)
25/02/19 00:38:52 INFO DAGScheduler: Parents of final stage: List()
25/02/19 00:38:52 INFO DAGScheduler: Missing parents: List()
25/02/19 00:38:52 INFO DAGScheduler: Submitting ResultStage 0 (MapPartitionsRDD[3] at csv at App.scala:14), which has no missing parents
25/02/19 00:38:52 INFO MemoryStore: Block broadcast_1 stored as values in memory (estimated size 13.8 KiB, free 434.2 MiB)
25/02/19 00:38:52 INFO MemoryStore: Block broadcast_1_piece0 stored as bytes in memory (estimated size 6.5 KiB, free 434.2 MiB)
25/02/19 00:38:52 INFO BlockManagerInfo: Added broadcast_1_piece0 in memory on 10.255.255.254:43927 (size: 6.5 KiB, free: 434.4 MiB)
25/02/19 00:38:52 INFO SparkContext: Created broadcast 1 from broadcast at DAGScheduler.scala:1585
25/02/19 00:38:52 INFO DAGScheduler: Submitting 1 missing tasks from ResultStage 0 (MapPartitionsRDD[3] at csv at App.scala:14) (first 15 tasks are for partitions Vector(0))
25/02/19 00:38:52 INFO TaskSchedulerImpl: Adding task set 0.0 with 1 tasks resource profile 0
25/02/19 00:38:52 INFO TaskSetManager: Starting task 0.0 in stage 0.0 (TID 0) (10.255.255.254, executor driver, partition 0, PROCESS_LOCAL, 9896 bytes) 
25/02/19 00:38:52 INFO Executor: Running task 0.0 in stage 0.0 (TID 0)
25/02/19 00:38:52 INFO CodeGenerator: Code generated in 12.528525 ms
25/02/19 00:38:52 INFO FileScanRDD: Reading File path: file:///mnt/g/scala/example-spark-scala/customers-100.csv, range: 0-17255, partition values: [empty row]
25/02/19 00:38:52 INFO CodeGenerator: Code generated in 40.709858 ms
25/02/19 00:38:53 INFO Executor: Finished task 0.0 in stage 0.0 (TID 0). 1800 bytes result sent to driver
25/02/19 00:38:53 INFO TaskSetManager: Finished task 0.0 in stage 0.0 (TID 0) in 697 ms on 10.255.255.254 (executor driver) (1/1)
25/02/19 00:38:53 INFO TaskSchedulerImpl: Removed TaskSet 0.0, whose tasks have all completed, from pool
25/02/19 00:38:53 INFO DAGScheduler: ResultStage 0 (csv at App.scala:14) finished in 0.890 s
25/02/19 00:38:53 INFO DAGScheduler: Job 0 is finished. Cancelling potential speculative or zombie tasks for this job
25/02/19 00:38:53 INFO TaskSchedulerImpl: Killing all running tasks in stage 0: Stage finished
25/02/19 00:38:53 INFO DAGScheduler: Job 0 finished: csv at App.scala:14, took 0.965247 s
25/02/19 00:38:53 INFO CodeGenerator: Code generated in 17.506485 ms
25/02/19 00:38:53 INFO FileSourceStrategy: Pushed Filters: 
25/02/19 00:38:53 INFO FileSourceStrategy: Post-Scan Filters:
25/02/19 00:38:53 INFO MemoryStore: Block broadcast_2 stored as values in memory (estimated size 199.5 KiB, free 434.0 MiB)
25/02/19 00:38:53 INFO MemoryStore: Block broadcast_2_piece0 stored as bytes in memory (estimated size 34.4 KiB, free 433.9 MiB)
25/02/19 00:38:53 INFO BlockManagerInfo: Added broadcast_2_piece0 in memory on 10.255.255.254:43927 (size: 34.4 KiB, free: 434.3 MiB)
25/02/19 00:38:53 INFO SparkContext: Created broadcast 2 from csv at App.scala:14
25/02/19 00:38:53 INFO FileSourceScanExec: Planning scan with bin packing, max size: 4211559 bytes, open cost is considered as scanning 4194304 bytes.
25/02/19 00:38:53 INFO FileSourceStrategy: Pushed Filters: 
25/02/19 00:38:53 INFO FileSourceStrategy: Post-Scan Filters:
25/02/19 00:38:53 INFO CodeGenerator: Code generated in 12.86595 ms
25/02/19 00:38:53 INFO MemoryStore: Block broadcast_3 stored as values in memory (estimated size 199.4 KiB, free 433.7 MiB)
25/02/19 00:38:53 INFO MemoryStore: Block broadcast_3_piece0 stored as bytes in memory (estimated size 34.4 KiB, free 433.7 MiB)
25/02/19 00:38:53 INFO BlockManagerInfo: Added broadcast_3_piece0 in memory on 10.255.255.254:43927 (size: 34.4 KiB, free: 434.3 MiB)
25/02/19 00:38:53 INFO SparkContext: Created broadcast 3 from count at App.scala:15
25/02/19 00:38:53 INFO FileSourceScanExec: Planning scan with bin packing, max size: 4211559 bytes, open cost is considered as scanning 4194304 bytes.
25/02/19 00:38:54 INFO DAGScheduler: Registering RDD 13 (count at App.scala:15) as input to shuffle 0
25/02/19 00:38:54 INFO DAGScheduler: Got map stage job 1 (count at App.scala:15) with 1 output partitions
25/02/19 00:38:54 INFO DAGScheduler: Final stage: ShuffleMapStage 1 (count at App.scala:15)
25/02/19 00:38:54 INFO DAGScheduler: Parents of final stage: List()
25/02/19 00:38:54 INFO DAGScheduler: Missing parents: List()
25/02/19 00:38:54 INFO DAGScheduler: Submitting ShuffleMapStage 1 (MapPartitionsRDD[13] at count at App.scala:15), which has no missing parents
25/02/19 00:38:54 INFO MemoryStore: Block broadcast_4 stored as values in memory (estimated size 18.8 KiB, free 433.7 MiB)
25/02/19 00:38:54 INFO MemoryStore: Block broadcast_4_piece0 stored as bytes in memory (estimated size 9.1 KiB, free 433.7 MiB)
25/02/19 00:38:54 INFO BlockManagerInfo: Added broadcast_4_piece0 in memory on 10.255.255.254:43927 (size: 9.1 KiB, free: 434.3 MiB)
25/02/19 00:38:54 INFO SparkContext: Created broadcast 4 from broadcast at DAGScheduler.scala:1585
25/02/19 00:38:54 INFO DAGScheduler: Submitting 1 missing tasks from ShuffleMapStage 1 (MapPartitionsRDD[13] at count at App.scala:15) (first 15 tasks are for partitions Vector(0))
25/02/19 00:38:54 INFO TaskSchedulerImpl: Adding task set 1.0 with 1 tasks resource profile 0
25/02/19 00:38:54 INFO TaskSetManager: Starting task 0.0 in stage 1.0 (TID 1) (10.255.255.254, executor driver, partition 0, PROCESS_LOCAL, 9885 bytes)
25/02/19 00:38:54 INFO Executor: Running task 0.0 in stage 1.0 (TID 1)
25/02/19 00:38:54 INFO CodeGenerator: Code generated in 11.085534 ms
25/02/19 00:38:54 INFO FileScanRDD: Reading File path: file:///mnt/g/scala/example-spark-scala/customers-100.csv, range: 0-17255, partition values: [empty row]
25/02/19 00:38:54 INFO CodeGenerator: Code generated in 7.906767 ms
25/02/19 00:38:54 INFO Executor: Finished task 0.0 in stage 1.0 (TID 1). 2105 bytes result sent to driver
25/02/19 00:38:54 INFO TaskSetManager: Finished task 0.0 in stage 1.0 (TID 1) in 320 ms on 10.255.255.254 (executor driver) (1/1)
25/02/19 00:38:54 INFO TaskSchedulerImpl: Removed TaskSet 1.0, whose tasks have all completed, from pool
25/02/19 00:38:54 INFO DAGScheduler: ShuffleMapStage 1 (count at App.scala:15) finished in 0.351 s
25/02/19 00:38:54 INFO DAGScheduler: looking for newly runnable stages
25/02/19 00:38:54 INFO DAGScheduler: running: HashSet()
25/02/19 00:38:54 INFO DAGScheduler: waiting: HashSet()
25/02/19 00:38:54 INFO DAGScheduler: failed: HashSet()
25/02/19 00:38:54 INFO BlockManagerInfo: Removed broadcast_2_piece0 on 10.255.255.254:43927 in memory (size: 34.4 KiB, free: 434.3 MiB)
25/02/19 00:38:54 INFO BlockManagerInfo: Removed broadcast_1_piece0 on 10.255.255.254:43927 in memory (size: 6.5 KiB, free: 434.3 MiB)
25/02/19 00:38:54 INFO BlockManagerInfo: Removed broadcast_0_piece0 on 10.255.255.254:43927 in memory (size: 34.4 KiB, free: 434.4 MiB)
25/02/19 00:38:54 INFO CodeGenerator: Code generated in 12.077153 ms
25/02/19 00:38:54 INFO SparkContext: Starting job: count at App.scala:15
25/02/19 00:38:54 INFO DAGScheduler: Got job 2 (count at App.scala:15) with 1 output partitions
25/02/19 00:38:54 INFO DAGScheduler: Final stage: ResultStage 3 (count at App.scala:15)
25/02/19 00:38:54 INFO DAGScheduler: Parents of final stage: List(ShuffleMapStage 2)
25/02/19 00:38:54 INFO DAGScheduler: Missing parents: List()
25/02/19 00:38:54 INFO DAGScheduler: Submitting ResultStage 3 (MapPartitionsRDD[16] at count at App.scala:15), which has no missing parents
25/02/19 00:38:54 INFO MemoryStore: Block broadcast_5 stored as values in memory (estimated size 13.1 KiB, free 434.1 MiB)
25/02/19 00:38:54 INFO MemoryStore: Block broadcast_5_piece0 stored as bytes in memory (estimated size 6.1 KiB, free 434.1 MiB)
25/02/19 00:38:54 INFO BlockManagerInfo: Added broadcast_5_piece0 in memory on 10.255.255.254:43927 (size: 6.1 KiB, free: 434.4 MiB)
25/02/19 00:38:54 INFO SparkContext: Created broadcast 5 from broadcast at DAGScheduler.scala:1585
25/02/19 00:38:54 INFO DAGScheduler: Submitting 1 missing tasks from ResultStage 3 (MapPartitionsRDD[16] at count at App.scala:15) (first 15 tasks are for partitions Vector(0))
25/02/19 00:38:54 INFO TaskSchedulerImpl: Adding task set 3.0 with 1 tasks resource profile 0
25/02/19 00:38:54 INFO TaskSetManager: Starting task 0.0 in stage 3.0 (TID 2) (10.255.255.254, executor driver, partition 0, NODE_LOCAL, 9276 bytes)
25/02/19 00:38:54 INFO Executor: Running task 0.0 in stage 3.0 (TID 2)
25/02/19 00:38:54 INFO ShuffleBlockFetcherIterator: Getting 1 (60.0 B) non-empty blocks including 1 (60.0 B) local and 0 (0.0 B) host-local and 0 (0.0 B) push-merged-local and 0 (0.0 B) remote blocks
25/02/19 00:38:54 INFO ShuffleBlockFetcherIterator: Started 0 remote fetches in 15 ms
25/02/19 00:38:54 INFO CodeGenerator: Code generated in 8.620798 ms
25/02/19 00:38:54 INFO Executor: Finished task 0.0 in stage 3.0 (TID 2). 4084 bytes result sent to driver
25/02/19 00:38:54 INFO TaskSetManager: Finished task 0.0 in stage 3.0 (TID 2) in 97 ms on 10.255.255.254 (executor driver) (1/1)
25/02/19 00:38:54 INFO TaskSchedulerImpl: Removed TaskSet 3.0, whose tasks have all completed, from pool
25/02/19 00:38:54 INFO DAGScheduler: ResultStage 3 (count at App.scala:15) finished in 0.108 s
25/02/19 00:38:54 INFO DAGScheduler: Job 2 is finished. Cancelling potential speculative or zombie tasks for this job
25/02/19 00:38:54 INFO TaskSchedulerImpl: Killing all running tasks in stage 3: Stage finished
25/02/19 00:38:54 INFO DAGScheduler: Job 2 finished: count at App.scala:15, took 0.120309 s
Count: 100
25/02/19 00:38:54 INFO SparkContext: SparkContext is stopping with exitCode 0.

在 Windows 11 使用 Ollama 執行 Chat AI

2025-02-05T01:19:00.001+08:00

在本機想要執行大型語言模型，目前常見的方法就是透過 Ollama。所以這篇稍微紀錄一下需要做哪些事。不過其實要做的很少，跟之前裝 Stable Diffusion 比起來，Ollama 非常容易 😆

首先，先去 Ollama 官網下載 Ollama 安裝，這個步驟就跟一般裝 Windows 應用程式一樣，有安裝介面，所以沒什麼特殊的動作。
如果有 nVIdia 顯卡，建議裝一下 CUDA Toolkit。
打開 PowerShell，輸入 ollama -h，會列出 Ollama 可以用的指令。

> ollama -h
Large language model runner

Usage:
  ollama [flags]
  ollama [command]

Available Commands:
  serve       Start ollama
  create      Create a model from a Modelfile
  show        Show information for a model
  run         Run a model
  stop        Stop a running model
  pull        Pull a model from a registry
  push        Push a model to a registry
  list        List models
  ps          List running models
  cp          Copy a model
  rm          Remove a model
  help        Help about any command

Flags:
  -h, --help      help for ollama
  -v, --version   Show version information

Use "ollama [command] --help" for more information about a command.

在進入下一步開始正式執行之前，建議可以考慮在環境變數設定 OLLAMA_MODELS。這是因為 Ollama 預設會在使用者目錄下的 /.ollama 資料夾中放下載的 model，有些比較大的 model 甚至有幾百 GB 的，因此建議透過設定 OLLAMA_MODELS 環境變數，讓 Ollama 把 model 下載到其他非 C: 的路徑。注意設了環境變數以後，要把 Ollama 完全關閉再重啟才會生效。
然後就可以實驗了，先拿 Llama 3.2 試試。輸入 ollama run llama3.2 就可以自動下載 Llama 3.2 的 model 並執行。

> ollama run llama3.2
pulling manifest
pulling dde5aa3fc5ff... 100% ▕███████████████████████████████████████████████████████████████▏ 2.0 GB
pulling 966de95ca8a6... 100% ▕███████████████████████████████████████████████████████████████▏ 1.4 KB
pulling fcc5a6bec9da... 100% ▕███████████████████████████████████████████████████████████████▏ 7.7 KB
pulling a70ff7e570d9... 100% ▕███████████████████████████████████████████████████████████████▏ 6.0 KB
pulling 56bb8bd477a5... 100% ▕███████████████████████████████████████████████████████████████▏   96 B
pulling 34bb5ab01051... 100% ▕███████████████████████████████████████████████████████████████▏  561 B
verifying sha256 digest
writing manifest
success
>>>

接著就可以開始跟 Llama 對話了。之後大概就只剩要用哪個 model 之類的而已，可以參考 Ollama 的 models 頁面，看看有哪些 model 以及哪些大小可以選。

[筆記] Fluentd log driver 的 fluent-buffer-limit 定義

2024-12-25T01:07:00.002+08:00

在過去，fluent-buffer-limit 的定義是用 byte 來指定的，但在 docker 19.0.3 以後，同樣的參數，定義變成 log 行數了。所以這有可能導致 docker log driver 使用了遠比預期還多的記憶體。

https://github.com/moby/moby/issues/41488

[筆記] Apache HTTP Client 5 的注意事項

2024-11-26T23:45:00.007+08:00

要控制 timeout，應該使用的是 RequestConfig 裡的 connectTimeout，而不是 responseTimeout。
responseTimeout 從原始碼來看，跟 socketTimeout 是差不多的東西。
socketTimeout 代表的意思是距離上一次 network I/O 的時間差。也就是說，如果設定 socketTimeout 為 nms，則每 n-1 ms 收到一個封包，也是不會觸發 timeout 的。

[筆記] AWS ECS 問題排查筆記

2024-07-12T22:36:00.002+08:00

快速筆記，最近花了非常多時間在研究為什麼 ECS 底下的 EC2 作業系統從 CentOS 7 升級成 Amazon Linux 2023 後，上頭的 ECS container 出現一堆問題。

主要遇到的問題似乎是 I/O 的緣故。EBS I/O 超過部署時設定的 throughput 的話，會導致 EC2 變得很不穩定，例如無法 SSH 進入 EC2、或者 EC2 上的 ECS agent 會斷線等等。這個問題可能會衍生出 EC2 上的 ECS container 無法正常寫檔案，要寫入檔案的內容可能會一直被 cache 在 dirty page 上，導致 container 的記憶體用量超出預期。

至於為什麼 EBS I/O 的用量會超出部署的設定，這點暫時還沒有結論，不過 architect 有發現 Amazon Linux 2023 寫 system journal 寫蠻多的，相較來說，CentOS 幾乎不寫 system journal。

Spring Cache + AspectJ 背後的大致流程

2024-06-15T21:54:00.006+08:00

因為最近在專案中整合 Spring Cache，不過原生的 Spring Cache 支援的功能有點基本，我們想要擴充它的功能，所以需要稍微了解一下 Spring Cache 背後到底怎麼運作的，我們才有辦法找出比較合適的擴充方式。

網路上可以找到一些中國網友的原始碼解析，不過大多數找到的都是用預設的 Spring AOP，但我們專案的狀況會使用 AspectJ，所以這邊會紀錄 AspectJ 的狀況是如何運作的。

另外，因為我們還在用 Spring Boot 2.7，所以這裡會先關注在 Spring v5.3.31 版的原始碼。相關的 Spring Cache 官方文件可以參考這裡。

Spring Cache 的使用方式

那麼要從哪裡開始追蹤呢？先來看一下 Spring Cache 怎麼使用的。

@Configuration
@EnableCaching
public class AppConfig {
}

@Cacheable("books")
public Book findBook(ISBN isbn) {...}

Spring Cache 最基本的使用方式，就是像上面的例子那樣，用 @Cacheable 註解來告訴 Spring 說 findBook(...) 這個 method 要被 cache，並且需要提供一個 configuration，上面有 @EnableCaching 來要求要啟用 cache。這裡其實還需要一點其他的設定，不過因為不是這裡的重點，所以我都先略過 😆。總之，起點就是 @EnableCaching 了。

Cache 的載入流程

載入 Configuration

首先從 @EnableCaching 這個註解開始看，它的內容大概是這樣：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Import(CachingConfigurationSelector.class)
public @interface EnableCaching {
}

可以注意到，它宣告了 @Import，因此 Spring 會使用它指定的 CachingConfigurationSelector 來得知到載入什麼東西。

CachingConfigurationSelector (git) 是一個透過 parent 實作了 ImportSelector 的類別，因此它主要提供 selectImports 這個方法，用來告訴 Spring 說要載入的 class 的 FQDN 是什麼。比較重要的內容如下：

public class CachingConfigurationSelector extends AdviceModeImportSelector<EnableCaching> {
  ...
  private static final String CACHE_ASPECT_CONFIGURATION_CLASS_NAME =
            "org.springframework.cache.aspectj.AspectJCachingConfiguration";
  ...

  @Override
  public String[] selectImports(AdviceMode adviceMode) {
    switch (adviceMode) {
      case PROXY:
        return getProxyImports();
      case ASPECTJ:
        return getAspectJImports();
      default:
        return null;
    }
  }

  ...
  private String[] getAspectJImports() {
    List<String> result = new ArrayList<>(2);
    result.add(CACHE_ASPECT_CONFIGURATION_CLASS_NAME);
    if (jsr107Present && jcacheImplPresent) {
      result.add(JCACHE_ASPECT_CONFIGURATION_CLASS_NAME);
    }
    return StringUtils.toStringArray(result);
    }

在 selectImports() 中，會依據註解設定的 adviceMode 決定 import 時要給哪個 class name，因為前面提到我們要用的是 AspectJ，並且我們並沒有要用 JSR-107，所以這裡就只看純 AspectJ 的狀況。所以可以看出，這裡如果 adviseMode 設定為 AspectJ 的話，它會回覆的 FQDN 是 org.springframework.cache.aspectj.AspectJCachingConfiguration。

於是接著來看一下 AspectJ 的 Configuration (git) 寫了什麼～。

@Configuration(proxyBeanMethods = false)
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
public class AspectJCachingConfiguration extends AbstractCachingConfiguration {

  @Bean(name = CacheManagementConfigUtils.CACHE_ASPECT_BEAN_NAME)
  @Role(BeanDefinition.ROLE_INFRASTRUCTURE)
  public AnnotationCacheAspect cacheAspect() {
    AnnotationCacheAspect cacheAspect = AnnotationCacheAspect.aspectOf();
    cacheAspect.configure(this.errorHandler, this.keyGenerator, this.cacheResolver, this.cacheManager);
    return cacheAspect;
  }

}

這裡最主要就是提供一個 Bean，這個 Bean 是用來建立 AnnotationCacheAspect 的，並且在建立的同時會把註解上的設定、以及其他需要建立的例如 ErrorHandler、KeyGenerator、CacheResolver、CacheManager 等東西都一起注入進去。

所以到這裡稍微總結一下，這整段代表的意思，是當 Spring 讀到 @EnableCaching 註解時，會基於這個 Selector 決定去載入指定的 Configuration，然後就會依據 Configuration 的內容去建立包含 CacheManager 等等的 Bean，並且初始化一個 Aspect，把那些 Aspect 需要用到的 Bean 注入到 Aspect 當中。

Aspect 被初始化以後，後面的主要工作應該就是 AspectJ 的範疇了。不過因為我目前還沒有很完整地看過 AspectJ 的文件，所以只有大略知道一些資訊，如果紀錄有誤歡迎提醒 😆。

AspectJ 在縫合的時候，會讓 Aspect 擁有 aspectOf() 的 method (doc)，所以 Spring 才有辦法呼叫 aspectOf() 來取得這個 Aspect，並且對它做設定。

載入並註冊 Aspect

前段被建立的 AnnotationCacheAspect (git) 是一個 .aj 檔，所以內容基本上就是 AspectJ 的定義了：

public aspect AnnotationCacheAspect extends AbstractCacheAspect {

  public AnnotationCacheAspect() {
    super(new AnnotationCacheOperationSource(false));
  }

  /**
   * Matches the execution of any public method in a type with the @{@link Cacheable}
   * annotation, or any subtype of a type with the {@code @Cacheable} annotation.
   */
  private pointcut executionOfAnyPublicMethodInAtCacheableType() :
      execution(public * ((@Cacheable *)+).*(..)) && within(@Cacheable *);

  ...

  /**
   * Definition of pointcut from super aspect - matched join points will have Spring
   * cache management applied.
   */
  protected pointcut cacheMethodExecution(Object cachedObject) :
    (executionOfAnyPublicMethodInAtCacheableType()
        || executionOfAnyPublicMethodInAtCacheEvictType()
        || executionOfAnyPublicMethodInAtCachePutType()
        || executionOfAnyPublicMethodInAtCachingType()
        || executionOfCacheableMethod()
        || executionOfCacheEvictMethod()
        || executionOfCachePutMethod()
        || executionOfCachingMethod())
      && this(cachedObject);

這裡我把其他部份都略過了，只先看它定義關於 @Cacheable 的部份。它定義了一個 pointcut 叫做 executionOfAnyPublicMethodInAtCacheableType()，會被橫切到所有有標註 @Cacheable 的 public method 上。那麼 pointcut 要執行的邏輯是什麼呢？這就需要看它的 parent AbstractCacheAspect (git) 了。

public abstract aspect AbstractCacheAspect extends CacheAspectSupport implements DisposableBean {
  ...
  @SuppressAjWarnings("adviceDidNotMatch")
  Object around(final Object cachedObject) : cacheMethodExecution(cachedObject) {
    MethodSignature methodSignature = (MethodSignature) thisJoinPoint.getSignature();
    Method method = methodSignature.getMethod();

    CacheOperationInvoker aspectJInvoker = new CacheOperationInvoker() {
        public Object invoke() {
          try {
            return proceed(cachedObject);
          }
          catch (Throwable ex) {
            throw new ThrowableWrapper(ex);
          }
        }
    };

    try {
      return execute(aspectJInvoker, thisJoinPoint.getTarget(), method, thisJoinPoint.getArgs());
    }
    catch (CacheOperationInvoker.ThrowableWrapper th) {
      AnyThrow.throwUnchecked(th.getOriginal());
      return null; // never reached
    }
  }
}

可以看出，它定義了一個 around 並綁定在 cacheMethodExecution() 上，而 cacheMethodExecution() 這個 pointcut 則是定義一系列的 pointcuts。所以我的理解是，它應該是把 around 綁到所有它列出來的 pointcut，也就是像是 @Cacheable、`CachePut 等等的 pointcut。

接著來看這個 around 裡面的內容。它首先先建立了一個 CacheOperationInvoker 的 instance，這個 invoker 的目的是用來呼叫被 cache 的 method 的，接著就去呼叫 execute()，把 JoinPoint 的資訊以及剛剛建立的 invoker 都傳進去。

execute() 是 AbstractCacheAspect 從它的 parent CacheAspectSupport 繼承來的，所以接著就再去看 CacheAspectSupport 裡的內容。不過裡面內容蠻多的，所以只先節錄了 execute() 的部份：

@Nullable
protected Object execute(CacheOperationInvoker invoker, Object target, Method method, Object[] args) {
  // Check whether aspect is enabled (to cope with cases where the AJ is pulled in automatically)
  if (this.initialized) {
    Class<?> targetClass = getTargetClass(target);
    CacheOperationSource cacheOperationSource = getCacheOperationSource();
    if (cacheOperationSource != null) {
      Collection<CacheOperation> operations = cacheOperationSource.getCacheOperations(method, targetClass);
      if (!CollectionUtils.isEmpty(operations)) {
        return execute(invoker, method,
            new CacheOperationContexts(operations, method, args, target, targetClass));
      }
    }
  }

  return invoker.invoke();
}

這段最主要的行為，是在檢查自己初始化的狀態，如果初始化還沒完成，就直接呼叫 invoker，否則就把 cache 的服務 (即 CacheOperationSource) 準備好，然後再去呼叫第二個 execute()。

第二個 execute() (git) 內容更長，所以這裡也是先篩掉一些內容，只先看最單純的部份：

private Object execute(final CacheOperationInvoker invoker, Method method, CacheOperationContexts contexts) {
  // Special handling of synchronized invocation
  if (contexts.isSynchronized()) {
    ...
  }

  ...

  // Check if we have a cached value matching the conditions
  Cache.ValueWrapper cacheHit = findCachedItem(contexts.get(CacheableOperation.class));

  ...

  Object cacheValue;
  Object returnValue;

  if (cacheHit != null && !hasCachePut(contexts)) {
    // If there are no put requests, just use the cache hit
    cacheValue = cacheHit.get();
    returnValue = wrapCacheValue(method, cacheValue);
  }
  else {
    // Invoke the method if we don't have a cache hit
    returnValue = invokeOperation(invoker);
    cacheValue = unwrapReturnValue(returnValue);
  }

  ...

  // Process any collected put requests, either from @CachePut or a @Cacheable miss
  for (CachePutRequest cachePutRequest : cachePutRequests) {
    cachePutRequest.apply(cacheValue);
  }

  ...

  return returnValue;
}

節錄下來的部份就是 Spring Cache 實際上操作 cache 服務和被 cache 的 method 的行為了。首先它透過 findCachedItem() 取得 cache 的結果，如果 cache hit 了，就把它放進 returnValue 中；反之，如果 cache miss 了，則會去執行被 cache 的 method 取得最新的執行結果，然後放進 returnValue 裡。

中間有一部分收集 put requests 的程式碼被我過濾掉了沒貼進來，不過大致上就是最後它會依據收集到要做的 put requests 開始一個一個 apply 到 cache 中，完成 cache 的更新。

Matryoshka Representation Learning (MRL) 與 Vespa

2024-05-05T14:09:00.007+08:00

這幾天經由 Vespa 的文章，讀到 OpenAI 在今年（2024 年）二月份的一篇在解說 MRL (Matryoshka Representation Learning) 的文章，看起來真的相當有趣！不過我並不是這個領域的專業，所以細部的內容我也沒有完全理解，這篇筆記大體只是我自己在應用上的基本理解。如果內容有誤也歡迎留言提醒。😇

MRL 是什麼？

Matryoshka doll 就是俄羅斯娃娃，而 Matryoshka Representation Learning 就是一種利用類似俄羅斯娃娃的特性（小的娃娃可以被裝進大的娃娃裡）做出來的 Embedding 方法，或者說是東西的表達手法。

那麼 MRL 跟其他 Embedding 方法最大的差異是什麼呢？就我目前的理解，最大的差異就是上述提到的，它具有俄羅斯娃娃的特性。具體來說，就是小的 Embedding 可以被放在大的 Embedding 裡，或者說是大的 Embedding 切割掉尾巴後，就幾乎等於是小的 Embedding。這個特性最主要的優勢，是在於我們可以不用針對不同維度的 Embedding 分別儲存不同的 Embedding，而是可以統一存一個 Embedding，在需要高維的時候使用 Embedding 裡的比較多內容、需要低維（更快更低成本）的時候則使用 Embedding 裡的一部份內容即可。

Vespa 與 MRL

那麼回到 Vespa 的使用情境，MRL 可以帶來什麼效果呢？首先如同 MRL 文章在上圖中提到的，MRL 會很適合用在 multi-phase ranking 的場合，例如先使用低維度來找出較符合結果的 candidates，然後第二階段時再針對這些 candidates 使用高維度來做更精準的計算，找出最佳的結果。

在 Vespa 二月份的文章中，首先提到他們做了一點基本的實驗，發現 MRL 產生的 Embedding 在使用相同模型的情況下，產生 8-dimension 跟 3072-dimension 的 Embedding，確實中間只差了 scale 而已，本質上非常相似。接著他們實際實驗了把 3072-dimension 的 Embedding，裁掉尾巴並只留下最前面的 8-dimension，然後去跟一開始就用 8-dimension 產生的 Embedding 做 cosine similarity 比較，發現兩者的相似度高達 99.99999999999996% 。

最後，Vespa 團隊用 COVID-19 的資料集做了實際的搜尋實驗，分別有以下幾種：

query_exact - 使用完整的 3072-dimension 並且不使用 ANN，也就是做最精準的語義搜尋。
query_256 - 改為使用 256-dimension 的低維度 Embedding，同樣也不使用 ANN。
query_256_ann - 使用 256-dimension 的低維度 Embedding，同時使用 ANN 做語義搜尋。
query_rerank - 使用 256-dimension 的 Embedding 作為 1st-phase，選出 top 100，然後用 3072-dimension 作為 2nd-phase
結果如下：

run query_exact
.................................................. avg query time 2.7918 s
run query_256
.................................................. avg query time 0.3040 s
run query_256_ann
.................................................. avg query time 0.0252 s
run query_rerank
.................................................. avg query time 0.0310 s

query_exact     ndcg_cut_10: 0.7870
query_256     ndcg_cut_10: 0.7574
query_256_ann     ndcg_cut_10: 0.7552
query_rerank     ndcg_cut_10: 0.7886

先看效能的部份，從 3072-dimensions 改為使用 256-dimensions 可以大幅加快搜尋速度，query time 只有原本的大約 11% 而已。而使用 ANN 的話，跟最開始的 query_exact 比較，甚至是只用了不到 1% 的時間！但效能提昇了，搜尋結果變差了多少呢？從 NDCG 來看，差異從 0.787 下降到 0.755 ，其實差異並沒有非常顯著。

如果我們直接比較 query_exact 跟 query_rerank 的話，得到的結果是 query time 是原本的 1.1% ，而 NDCG 幾乎一樣！從數據來看，MRL 的潛力真的相當大 😍

Stable Diffusion 加速

2024-03-18T23:03:00.001+08:00

簡要紀錄一下目前測試過的 Stable Diffusion 加速方法。之後如果有再看到其他通用的作法，也會視情況再紀錄過來這篇文章。

xformer
cuDNN

目前這裡紀錄的時間，會用以下的環境設定來測試時間。至於為什麼用這個呢？其實沒什麼原因，就隨便找一個 XD。

Windows 11
Stable Diffusion webui 1.8.0
checkpoint 模型：Mistoon_Anime v3.0

正向提示詞：

masterpiece,best quality,1girl,solo,girls und panzer,messy hair,smallbreasts,brown hair,long hair,orange eyes,side pony tail,beach,swimsuit,swim suit,smug,full body,

反向提示詞：

EasyNegative,(worst quality:1.4),(low quality:1.4),

batch size：4

啟用 xformer

這個選項目前還不太清楚傷害是什麼，似乎基本是無害的，不過有看到像是 openpose 會建議記憶體較低的話可以開，有可能實際上是對成品有點傷害。但對 Stable Diffusion 生圖的效能影響很大，所以如果手上的顯卡不是那麼強大的話，推薦可以考慮。具體來說，我自己的簡單測試結果是啟用後，生圖的時間大約減少了 48%（33.2s -> 17.3s），也就是減少將近一半！

啟用方法在現在很簡單，因為 xformer 已經變成 Stable Diffusion webui 的內建套件了，只是預設沒有啟用而已，所以只需要在 webui-user.bat 裡的 call webui.bat 後面加上 --xformers 就可以了。詳細的說明可以參考 Stable Diffusion webui 的 wiki 中關於 xformer 的說明。

call webui.bat --xformers

安裝 cuDNN

這個部份可以參考 reddit 的討論，不過我自己實際測試的結果，cuDNN 有沒有裝好像沒有差別，cuDNN 單獨測試、跟同時啟用 xformer 都有測過，但結果都沒有顯著差異。測試出來的數據如下：

features	time
vanilla	33.2s
cudnn	33.2s
xformer	17.3s
cudnn + xformer	17.6s

不過實際上這好像是要去更新 Stable Diffusion 裡的 PyTorch 使用到的 cuDNN 函式庫，因為裡面本來就已經有那 7 個 DLL 檔案了，安裝過程是要把下載下來的 cuDNN 裡的 DLL 覆蓋進去 PyTorch 的資料夾。所以也有可能純粹是因為我用 Stable Diffusion 1.8.0，裡面的 PyTorch 已經更新了它的 cuDNN，所以我測起來才測不出差別。

安裝方法的部份，由於這裡安裝的目的是要給 Stable Diffusion 使用，所以 nVidia 現在有提供的 Windows installer 好像是沒什麼用，因為它會把那些 DLL 裝進 Program Files 裡 XD。還有一點是 webui 1.8.0 的 PyTorch 使用的 cuDNN 似乎是 8.x 版，所以要注意不要下載到最新的 9.0 版，所以推薦是直接去官方的 archive 頁面下載，在我下載的這個時候，8.x 版中的最新版是 8.9.7.29。如果下載錯的話，要把檔案複製到 PyTorch 裡的時候，會發現所有檔案都是新增進去，沒有覆蓋到任何一個檔案，這樣它就不會真的被使用到。下載完以後，把資料夾裡 \bin 裡的總共 7 個 DLL 檔案全部複製到 Stable Diffusion webui 裡的 \venv\Lib\site-packages\torch\lib 並取代裡面同樣檔名的檔案即可。

Stable Diffusion 基本環境安裝

2024-03-07T01:22:00.012+08:00

講到繪圖 AI，在初期最有名的應該就是 Midjourney (MJ) 和 Stable Diffusion (SD) 了。後來雖然有不少其他名字陸續冒出來，不過最開始的這兩個，還是依然維持著它們的名氣。因為 side project 的關係，想要試試看繪圖 AI，所以就簡單研究了一下這兩個，發現 Stable Diffusion 可以在自己電腦上面跑，不用買訂閱制的服務！所以就決定嘗試它了！

說是這麼說，但簡單嘗試後發現一個很大的問題，Stable Diffusion 對非 nVidia 顯示卡的使用者相當不友善 😓。雖然不是完全不能用，但就圖片產生速度非常慢，而且環境準備也很麻煩。因為我的顯示卡是 AMD 的大概七年前的中階顯卡，搜尋了一下發現要用 AMD 算圖的環境設定超麻煩，所以立刻就放棄了 😆。試完了一下用 CPU 算圖，不過使用經驗是很多 model 都會有問題，而能用的又很慢，跑一張圖要跑 10 幾分鐘，所以試玩一下後就決定還是要去買新的顯示卡了。於是這篇就會簡單紀錄一下在 Windows 10 的 nVidia 顯卡以及 Stable Diffusion 的基本準備。

準備 NVIDIA 環境

NVIDIA 環境具體來說，就是顯示卡的驅動程式跟 CUDA 相關的東西。這個步驟不算太難，主要要安裝的是以下幾個東西：

NVIDIA Geforece Experience（2025 更新：後來改名叫 Nvidia App）
CUDA Toolkit
NVIDIA cuDNN

其中 Geforece Experience 其實本來不是必要的，不過因為顯示卡驅動程式好像都跟在這裡面，所以多半會一起裝進去。至於 cuDNN 真的就是非必要的，我自己的實際實驗是沒裝它也可以正常使用 Stable Diffusion，不過看官方的說明，感覺這個應該是對計算會有加速的效果之類的，所以還是裝一裝會比較好（但我現在還沒裝 😆）。

CUDA Toolkit 跟 cuDNN 安裝的版本都應該要參考自己的顯示卡和驅動程式對應的版本，可以分別參考官方網站的 CUDA GPU 和 CUDA Driver。舉例來說，在 CUDA Driver 頁面中有寫到 nVidia 驅動程式對應的 CUDA Driver 版本，所以要去看自己的驅動程式應該對應哪一個版本的 CUDA Driver。我的顯示卡有支援最新版，而在寫這篇文章的時候，CUDA Toolkit 最新版是 12.3 (最新版的下載位置) ，不過有個超級重要的經驗是，不要安裝 12.3 版 😆。我試過各種方法都沒辦法成功把 12.3 裝進去，安裝程式會一直顯示安裝失敗，但又不明確提示為什麼失敗。查了 NVIDIA 官方論壇以及 Reddit 的文章後，最後發現改安裝 12.2 (下載位置) 就可以順利安裝完成。

至於 cuDNN，因為我自己沒裝，所以如果之後有裝了再回來補充，可以先參考官方網站的說明。

準備 Stable Diffusion 環境

Stable Diffusion 環境有超多文章和影片在教了，例如這篇，這裡就簡單紀錄了 😆。也可以參考這個影片。

安裝 Windows Store 的 Python 3.7。
下載 Stable Diffusion webui。
在 webui-user.bat 裡面設定 Python 位置。
執行 webui-user.bat，它會在 venv 資料夾裡建出環境。因為要下載不少東西，會需要一段時間。

到這裡其實 Stable Diffusion 就弄好了。不過聽說 Stable Diffusion 還有必裝外掛，裝了以後它才有實用價值。所以下面還會再紀錄一些外掛的基本資訊。

Stable Diffusion 外掛

外掛們據說是 Stable Diffusion 非常重要的東西，有些外掛沒裝，會讓 Stable Diffusion 很難控制，所以會有常見的一些必裝外掛。這裡逐步紀錄一些我自己找到的資訊，不過使用細節等到我有更多經驗後，再看要不要寫點文章紀錄吧～。

翻譯
- stable-diffusion-webui-localization-zh_TW - 繁體中文翻譯，推薦再搭配雙語外掛
- sd-webui-bilingual-localization - 雙語外掛。對入門來說，可以同時看到翻譯的中文和原文的英文，方便對照和熟悉用詞。
提示詞
- sd-webui-prompt-all-in-one - 可以直接從 webui 介面裡安裝。主要功能是提供不少類型的正向和負向提示詞，另外也可以自動幫忙將提示詞翻譯成英文。對於英文詞彙沒那麼熟悉的話，會非常有幫助。
ControlNet - 可以直接從 webui 介面裡安裝。主要用來提昇對圖的控制，必裝，否則 Stable Diffusion 產生的圖太隨機了很難控制。

另外紀錄有討論到各種外掛以及提示詞的文章：

Vespa 的 parent document + weightedSet 撞牆筆記

2023-10-23T22:02:00.005+08:00

簡要紀錄，最近遇到在 parent document 裡使用 weightedSet 做資料篩選的時候，本來還沒加 weightedSet 時，latency 是大約 25ms，加了 weightedSet 之後變成大約 730ms。

以下是當時的 schema 設定，簡要來說就是有個讓多個 child document 共用的欄位，叫做 sharedField，它被 child document 繼承時，欄位名字會叫做 fieldInParentDoc。

# Schema in parent document.
field sharedField type weightedset<string> {
    indexing: attribute
    attribute: fast-search
}

# Schema in child document
field id type string {
    indexing: attribute
    attribute: fast-search
}

field parentReference type reference<parent_doc> {
    indexing: attribute
}

import field parentReference.sharedField as fieldInParentDoc {}

接著，在查詢時使用的 query 大約是這樣：

SELECT * FROM * sources WHERE (id contains "my_id_1" OR id contains "my_id_2") AND weightedSet(fieldInParentDoc, {"my_key":1});

實際上 ID 欄位是唯一值，並且 query 當中會有 5 個 ID，所以搜尋結果一定只會有 5 筆紀錄。理論上這應該會是很快的 query，但在加上後半段的 parent document 篩選條件後，速度就爆增了 28 倍。

不過如果幫這個 parent document 欄位設定 rank: filter，如下所示，讓它改成 bit vector 的形式，速度會變快不少。具體來說，專案裡測試的結果是會從 730ms 變成約 90ms。雖然還是很慢，但至少勉強還過得去…。

# Schema in parent document.
field sharedField type weightedset<string> {
    indexing: attribute
    attribute: fast-search
    rank: filter
}

在 Vespa 使用語義搜尋（一）：簡要的基本知識

2023-10-11T02:10:00.002+08:00

在搜尋的世界裡，語義搜尋（semantic search）是近代非常熱門的作法，它可以做到一些傳統的文字搜尋（text matching）做不到的事情。概念上來說，語義搜尋就是把句子的語義萃取出來，轉換成數學裡的向量來表達，然後再利用向量距離來衡量兩個句子的相關程度。這篇文章會簡要紀錄一點語義搜尋時，可能需要知道的基本知識。不過由於這裡面比較多跟資料科學比較有關的知識，在這方面我是個外行，所以這篇基本上都會比較以偏外行的視角在看待這些知識。

Vector Search

技術上來說，語義搜尋也可以稱之為 Vector Search，畢竟語義搜尋是透過向量來做搜尋。而要做語義搜尋，第一要務就是「要如何把一個字串轉換成向量」？這個轉換很大幅度決定了語義搜尋的結果，畢竟轉換成什麼樣的向量，就會決定它跟什麼東西比較近了。其中，把文字轉換成向量的行為，稱為詞嵌入（Embedding）。

Embedding 有很多種技術，近年來比較著名的演算法，就我所知大概是 BERT、FastText 等等的。具體來說，依據我們選擇的 embedding 演算法，會產生出不同維度的向量，這些向量放在向量空間中，就可以接著被用來計算點跟點的距離，並用以決定兩段文字是否相關。

Transformer

Transformer 是 Google 在 2017 年發表的神經網路架構，就我的理解是，這個架構最大的不同是讓神經網路的計算能夠平行化，使得大型模型的訓練變成了可能。目前比較常聽到的像是 GPT（Generative Pre-trained Transformers）、BERT（Bidirectional Encoder Representations from Transformers）等模型，都是基於 Transformer 架構開發出來的。

Hugging Face

由於市場上現在有很多種模型架構和應用環境，例如有些模型用 TensorFlow、有些用 PyTorch 等等。Hugging Face 是用來提供統一的 API 介面，使得不同架構的模型能夠互通。細節可以參考文章。

ONNX

ONNX（Open Neural Network Exchange）是一種神經網路的資料交換格式，用來讓不同架構（例如 Google 的 Tensorflow、Meta 的 PyTorch、微軟的 CNTX 等）訓練出來的模型能夠互通在其他架構。不過據說 Tensorflow 因為發展較早，已經有自己成熟的環境，因此並不支援 ONNX，但有工具能夠將 Tensorflow 模型轉換成 ONNX 格式，如 tf2onnx。

Nearest Neighbor Search

NN（Nearest Neighbor）是在向量空間中尋找最近的點的問題。比較著名的解法是 KNN（K-nearest neighbor algorithm）。

Approximate Nearest Neighbor Search

ANN（Approximate Nearest Neighbor Search）是改良版的 NN，目標是用比較粗略的方式，在向量空間中找出距離最近的點。Vespa 在使用 ANN 去計算尋找最近的點時，使用的演算法是 HNSW。

系統碟備份的經驗紀錄

2023-09-14T21:40:00.005+08:00

這兩天因為換系統碟，把古老的 Intel 240GB 換成美光 MX500 1TB，所以遇到一些奇怪的問題。簡單做個筆記。

首先是系統碟備份的部份，我是直接用 Macrium Reflect v8.0.6758。本來要下載安裝檔，正要安裝時發現原來電腦裡本來就有裝了，於是就直接用裝好的版本。不過新版的疑似沒有個人使用的免費版了？用這個直接在 Windows 裡就能夠對系統碟做 clone disk 了，還蠻方便的。

磁碟轉移完成後，我又做了一件事是把一顆快壞掉的硬碟拔掉，之前把那顆硬碟設成虛擬磁碟和暫存資料區，現在就直接不用它了。不過我完全忘了自己做了什麼設定，所以後來遇到奇奇怪怪的問題，其實都跟它有關。

首先遇到的問題，是 Line 沒辦法打開圖片，把 Line 重裝以後甚至變成連打開圖片需要的套件都裝不了，下載完後會顯示無法安裝。接著遇到我想刪掉 Line 重裝，結果用 Firefox 要下載時，發現 Firefox 無法下載檔案了，所有連結點了都是立刻失敗（但用 Firefox 以外的瀏覽器就可以下載）。接著我想找系統清理的軟體，嘗試想清理看看什麼登錄檔之類的，然後發現微軟也有出相關的軟體，就去下載微軟的安裝檔，結果安裝檔下載下來雙擊安裝時也失敗，無法安裝。最後是在 Edge 上下載某個檔案並從 Edge 點擊安裝時，才終於彈出一個錯誤訊息說「找不到 T:\」.....。這時我才終於注意到，原來這一系列奇奇怪怪的問題，都是因為某種暫存檔的設定，是設定在被我拔掉的那顆硬碟磁區上.....。於是去改了環境變數的 TEMP 和 TMP 路徑，換成另一顆硬碟，一切就恢復正常了。

OS：過程中我刪掉了 Line 和 Firefox，害我好多東西要重新設定....。但還好 Firefox ESR 移除重裝，它還找得到原本的百來個分頁，算是一個小雀幸了....。

除了 TEMP 造成的問題以外，還有另一個有點沒頭緒的問題是，換成新硬碟後，PPPoE 就再也連不上了。費了一番功夫（主要是依靠 ChatGPT 跟 Google）後，發現修復的方法似乎是先移除 PPPoE 設定，然後去裝置管理員，把所有「網路介面卡」底下的 WAN Miniport 全部移除，然後讓它重新掃描一次硬體變更，自動裝回那些 WAN Miniport 後，再重設一次 PPPoE，就可以修復了。也可以參考微軟的說明。

[書籤] GC Log Analyzer

2023-08-31T21:49:00.005+08:00

Azul 有提供免費的 GC log analyzer 可以用來把 gc log 圖形化。

https://docs.azul.com/prime/GC-Log-Analyzer

MapStruct 不支援 lombok fluent accessors

2023-08-15T17:41:00.003+08:00

快速筆記，MapStruct 沒有要支援 lombok 的 fluent accessors，因為這樣他們會掃出所有的 method 而無法正確判斷哪個 method 才是 getter/setter。

可以參考 Github issue：https://github.com/mapstruct/mapstruct/issues/3286

基本的 OpenTelemetry Metrics 設定：讓 Counter 只紀錄差異

2023-04-26T23:22:00.005+08:00

上一篇文章中，我用 LongCounter 來計算收到的 event 數量，並且讓 OTEL 每一秒輸出一次資料到 log 裡。不過其實這個作法跟我本來想像的結果不太相同，因為我想像的是例如第一秒收到 5 個 event、第二秒收到 7 個 event，OTEL 輸出的 Metrics 應該要是：

第一個 data point 是 5
第二個 data point 是 7
第三個 data point 是 0

但事實上當時寫出來的範例程式會輸出的結果會是：

第一個 data point 是 5
第二個 data point 是 12
第三個 data point 是 12

也就是說，範例程式紀錄下來的是累計值，是從 application 啟動開始累計到現在的所有數值的加總。但我希望紀錄下來的其實是差異值，每次 Exporter 輸出完 Metrics 後，我希望它重置 counter。

設定 Exporter 輸出差異值

要達成紀錄的是差異值，要做的事情是去設定 Exporter 的 AggregationTemporality。具體設定的方法其實每個 Exporter 都有點不一樣，不過都是在 ...Builder 的階段控制的。這裡繼續以 LoggingMetricExporter 為例，LoggingMetricExporter 設定 temporality 的方法如下：

LoggingMetricExporter.create(AggregationTemporality.DELTA);

測試方法

設定了 AggregationTemporality 之後，把測試的腳本稍微弄複雜一點，大體來說就是改成用 2 個 thread 模擬送出 1M 個 event，然後觀察 OTEL 紀錄到什麼東西。為了簡化測試，我把一些本來隨機的東西都拿掉，會比較方便觀察數字的正確性 XD。

@Override
public void run(String... args) throws Exception {
    log.info("Run");

    produceEvents(1_000_000, 10);

    log.info("Done");
}

private void produceEvents(int numOfEvents, int numOfThreads) {
    var executor = Executors.newFixedThreadPool(numOfThreads);

    for (int i = 0; i < numOfEvents; i++) {
        executor.submit(() -> {
            if (random.nextBoolean()) {
                processor1.receiveEvent(generateRandomEvent());
            } else {
                processor2.receiveEvent(generateRandomEvent());
            }
        });
    }
}

private Event generateRandomEvent() {
    var eventType = "create";

    return Event.builder()
            .eventType(eventType)
            .owner("owner-1")
            .build();
}

完整的範例程式可以參考這裡。

執行結果

以下是執行時，OTEL 輸出的結果。

INFO  i.o.e.l.LoggingMetricExporter [PeriodicMetricReader-1] Received a collection of 1 metrics for export.
INFO  i.o.e.l.LoggingMetricExporter [PeriodicMetricReader-1] metric: ImmutableMetricData{resource=Resource{schemaUrl=null, attributes={service.name="otel-example", telemetry.sdk.language="java", telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.22.0"}}, instrumentationScopeInfo=InstrumentationScopeInfo{name=event-consumer, version=1.0.0, schemaUrl=null, attributes={}}, name=eventType, description=Metrics for the event consuming., unit=1, type=LONG_SUM, data=ImmutableSumData{points=[ImmutableLongPointData{startEpochNanos=1682522136538247300, epochNanos=1682522137553247500, attributes={eventType="create", owner="owner-1"}, value=584412, exemplars=[]}], monotonic=true, aggregationTemporality=DELTA}}
INFO  i.o.e.l.LoggingMetricExporter [PeriodicMetricReader-1] Received a collection of 1 metrics for export.
INFO  i.o.e.l.LoggingMetricExporter [PeriodicMetricReader-1] metric: ImmutableMetricData{resource=Resource{schemaUrl=null, attributes={service.name="otel-example", telemetry.sdk.language="java", telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.22.0"}}, instrumentationScopeInfo=InstrumentationScopeInfo{name=event-consumer, version=1.0.0, schemaUrl=null, attributes={}}, name=eventType, description=Metrics for the event consuming., unit=1, type=LONG_SUM, data=ImmutableSumData{points=[ImmutableLongPointData{startEpochNanos=1682522137553247500, epochNanos=1682522138548844500, attributes={eventType="create", owner="owner-1"}, value=415588, exemplars=[]}], monotonic=true, aggregationTemporality=DELTA}}
DEBUG i.o.s.m.e.PeriodicMetricReader [PeriodicMetricReader-1] No metric data to export - skipping export.
DEBUG i.o.s.m.e.PeriodicMetricReader [PeriodicMetricReader-1] No metric data to export - skipping export.

文字太長了，稍微摘要一下：

....attributes={eventType="create", owner="owner-1"}, value=584412, exemplars=[]....
....attributes={eventType="create", owner="owner-1"}, value=415588, exemplars=[]....
....No metric data to export - skipping export.
....No metric data to export - skipping export.

可以看到它第一秒紀錄到的 count 是 584,412、第二秒紀錄到的是 415,588，兩秒合計就是 1M，正好是我的測試程式送出的數目。兩秒過去後，因為後續沒有再呼叫 method，所以 OTEL 沒有繼續收到新的 metric data，就會看到 skipping export 的訊息。

基本的 OpenTelemetry Metrics 設定：紀錄累計數目並透過 Spring AOP 攔截方法

2023-01-28T21:34:00.003+08:00

接續著前面的 Spring AOP，接著要在 Spring AOP 之上接 OpenTelemetry。實際上接 OpenTelemetry 才是我的目的，AOP 只是希望接 metric/tracing 時可以不要碰商業邏輯的程式碼而已 XD。

什麼是 OpenTelemetry

簡要來說，OpenTelemetry（簡稱 OTEL）是結合了 CNCF 發展的 OpenTracing 和 Google 發展的 OpenCensus 兩個專案後的結果 [1]，目的是為了提供 observibility telemetry。它涵蓋了三大主題：tracing、metrics、logs。tracing 能夠整合上下游的關係，提供完整的 profiling 資訊；metrics 能夠提供統計型的數據，讓我們可以快速了解系統的狀態；logs 則是文字型的資料。

不過就我目前的了解，OTEL 因為是在 2019 年才合併，到現在似乎還是沒有到非常完整，各個語言的支援有些可能還是有點缺漏。以 Java 來說，目前 tracing 和 metrics 的支援是比較好，logs 則還處於實驗中。細節可以參考 OTEL 官網中關於 Java SDK 的狀態頁 [2]。

OpenTelemetry Metrics 建置

因為我目前的目的是要建立 Metrics 的環境，把我的 Java application 的一些自訂資訊輸出到 Metrics 上，讓我們得以透過統計資訊了解系統的狀態，所以這篇主要只會紀錄關於 Metrics 的建置範例。

範例的目的

首先稍微簡介一下，這篇文章中的範例是設定成什麼背景、要解決什麼問題。承襲上一篇 Spring AOP 文章，我有一個 method 如下，這個 method 的角色是一個 event consumer，就是在收某種 queue 送過來的訊息。文章的目標是要透過 AOP 插入一個能夠統計收到的訊息的類型的 Metrics。有了這個 Metrics，就可以知道系統總共處理什麼量級的訊息，並且也可以用來做更細緻的統計，例如 Event 的設計是有分 eventType 和 owner，代表的是某個人送出的 Create/Update/Delete 指令，而 Metrics 希望能夠讓我們有能力得知例如在指定時間區間內，某個人送了多少指令、或者是總共有多少的 Create 指令等等。

@Slf4j
@Component
public class FakeEventProcessor {
    public void receiveEvent(Event event) {
        log.info("Receive: {}", event);
    }
}

@Builder
@Getter
@Accessors(fluent = true)
@ToString
public class Event {
    private String eventType;
    private String owner;
}

完整的範例程式碼，可以參考 [3]。

Gradle 設定

在 Gradle 中，需要加入以下的 dependencies：

// BOMs
implementation(platform("io.opentelemetry:opentelemetry-bom:1.22.0"))
implementation(platform("io.opentelemetry:opentelemetry-bom-alpha:1.22.0-alpha"))

implementation("io.opentelemetry:opentelemetry-api")
implementation("io.opentelemetry:opentelemetry-sdk")
implementation("io.opentelemetry:opentelemetry-semconv")

// Exporter
implementation("io.opentelemetry:opentelemetry-exporter-logging")

這裡可以看到 BOM 會有兩個，其中 opentelemetry-bom-alpha 是用來設定 opentelemetry-semconv 的 BOM，而 opentelemetry-semconv 的用途，在我目前的範例程式裡，好像只有初始化 OTEL 時要給的 ResourceAttribute 會用到它…。另外因為這裡我先實驗的目標是最簡單的 Metrics，所以是採取 Logging 作為 Metrics 的 Exporter。換句話說，就是我寫入的 Metrics 會以 log 的形式被輸出。

初始化 OpenTelemetry

要使用 OTEL 的 Metrics 之前，需要先在系統裡初始化一個 OpenTelemetry 的 instance。我的範例中會是使用 @Configuration 來讓 Spring 幫忙注入。

@Configuration
public class OpenTelemetryConfiguration {

    @Bean(destroyMethod = "")
    public OpenTelemetry getTelemetry() {
        var resource = Resource.getDefault()
                .merge(Resource.create(
                        Attributes.of(ResourceAttributes.SERVICE_NAME, "otel-example")));

        var sdkMeterProvider = SdkMeterProvider.builder()
                .registerMetricReader(
                        PeriodicMetricReader.builder(LoggingMetricExporter.create())
                                .setInterval(Duration.ofSeconds(1))
                                .build())
                .setResource(resource)
                .build();

        var openTelemetry = OpenTelemetrySdk.builder()
                .setMeterProvider(sdkMeterProvider)
                .buildAndRegisterGlobal();

        return openTelemetry;
    }
}

這裡首先用 Resource 做基本的環境設定，具體來說就只是設定一個 resource name 而已。接著因為我要產出 Metrics，所以需要的是 SdkMeterProvider。MeterProvider 的設定是輸出到 Logging，而且外面再包裝一層定時輸出的 MetricReader，設定為每一秒輸出一次。最後建出 OTEL 的 instance，把剛剛建立的 SdkMeterProvider 設定為它的 MeterProvider 即可。

在翻閱文件時，有個小細節是文件上有提到，如果是在為 library 建立 telemetry 的話，就建議不要 register global。雖然目前我還不太了解 register global 是什麼意思就是…。

建立 Aspect 為指定的 Method 插入 Metrics

文章最開頭有提到，我想要在插入 Metrics 統計的同時，不去修改既有的商業邏輯，所以 Metrics 的統計應該要發生在別的 class 而不應該直接寫在 FakeEventProcessor 中。因此我會另外建立一個 Aspect class，這個 class 會讓 Spring 注入上面寫到的 OpenTelemetry instance，然後在每次 FakeEventProcessor 的 receiveEvent(..) 被呼叫時，都攔截執行並把 event 的內容紀錄在 Metrics 當中。

@Slf4j
@Aspect
@Component
public class TelemetryAspect {

    private OpenTelemetry telemetry;

    private Meter meter;
    private LongCounter eventCounter;

    @Autowired
    public TelemetryAspect(OpenTelemetry telemetry) {
        log.trace("Initiate aspect...");
        this.telemetry = telemetry;
        initiateMeter();
    }

    private void initiateMeter() {
        meter = telemetry.meterBuilder("event-consumer")
                .setInstrumentationVersion("1.0.0")
                .build();

        eventCounter = meter.counterBuilder("eventType")
                .setDescription("Metrics for the event consuming.")
                .setUnit("1")
                .build();
    }

    @Before("execution(* tw.jimwayneyeh.example.otel.FakeEventProcessor.receiveEvent(..))")
    public void before(JoinPoint joinPoint) {
        var event = (Event) joinPoint.getArgs()[0];
        eventCounter.add(1, Attributes.of(
                AttributeKey.stringKey("eventType"), event.eventType(),
                AttributeKey.stringKey("owner"), event.owner()));
    }

在上述的程式碼中，首先我在 Aspect 被初始化時，會去初始化一個 Meter，因為這個 Meter 是統計數字，所以就直接命名為 eventCounter。接著在 JointPoint 中，每次 receiveEvent(..) 被呼叫時，AOP 會攔截這個 method 呼叫，取得 method 呼叫中送進來的 event 物件，並且把為 eventCounter +1。其中 +1 時加的對象，是對 eventType & owner 做 +1。

最後執行的結果會長這樣：

INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-0)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-1)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-1)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-1)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=delete, owner=owner-1)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=create, owner=owner-0)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-0)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=delete, owner=owner-1)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=create, owner=owner-0)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=delete, owner=owner-0)
INFO  t.j.e.otel.Run [main] Sleep...
INFO  i.o.e.l.LoggingMetricExporter [PeriodicMetricReader-1] Received a collection of 1 metrics for export.
INFO  i.o.e.l.LoggingMetricExporter [PeriodicMetricReader-1] metric: ImmutableMetricData{resource=Resource{schemaUrl=null, attributes={service.name="otel-example", telemetry.sdk.language="java", telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.22.0"}}, instrumentationScopeInfo=InstrumentationScopeInfo{name=event-consumer, version=1.0.0, schemaUrl=null, attributes={}}, name=eventType, description=Metrics for the event consuming., unit=1, type=LONG_SUM, data=ImmutableSumData{points=[ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="delete", owner="owner-1"}, value=2, exemplars=[]}, ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="create", owner="owner-0"}, value=2, exemplars=[]}, ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="delete", owner="owner-0"}, value=1, exemplars=[]}, ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="update", owner="owner-0"}, value=2, exemplars=[]}, ImmutableLongPointData{startEpochNanos=1674906020221141200, epochNanos=1674906021227565100, attributes={eventType="update", owner="owner-1"}, value=3, exemplars=[]}], monotonic=true, aggregationTemporality=CUMULATIVE}}

最上面 10 行是在 FakeEventProcessor 裡面寫的 log，然後因為我的 logging 設定為每秒輸出，所以故意讓主程式睡了一下，以避免主程式跑完迴圈以後就自己關掉了 XD。

i.o.e.l.LoggingMetricExporter 這段就是 Metrics 輸出的內容，稍微格式化一下：

ImmutableMetricData {
    resource = Resource {
        schemaUrl = null, attributes = {
            service.name = "otel-example",
            telemetry.sdk.language = "java",
            telemetry.sdk.name = "opentelemetry",
            telemetry.sdk.version = "1.22.0"
        }
    }, instrumentationScopeInfo = InstrumentationScopeInfo {
        name = event - consumer, version = 1.0 .0, schemaUrl = null, attributes = {}
    }, name = eventType, description = Metrics
    for the event consuming., unit = 1, type = LONG_SUM, data = ImmutableSumData {
        points = [ImmutableLongPointData {
            startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
                eventType = "delete",
                owner = "owner-1"
            }, value = 2, exemplars = []
        }, ImmutableLongPointData {
            startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
                eventType = "create",
                owner = "owner-0"
            }, value = 2, exemplars = []
        }, ImmutableLongPointData {
            startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
                eventType = "delete",
                owner = "owner-0"
            }, value = 1, exemplars = []
        }, ImmutableLongPointData {
            startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
                eventType = "update",
                owner = "owner-0"
            }, value = 2, exemplars = []
        }, ImmutableLongPointData {
            startEpochNanos = 1674906020221141200, epochNanos = 1674906021227565100, attributes = {
                eventType = "update",
                owner = "owner-1"
            }, value = 3, exemplars = []
        }], monotonic = true, aggregationTemporality = CUMULATIVE
    }
}

可以看到，Metrics 紀錄到的結果是：

owner-1 delete: 1
owner-0 create: 2
owner-0 delete: 1
owner-0 update: 2
owner-1 update: 3

確實結果是符合 FakeEventProcessor 的結果～。

Spring AOP 基本使用

2023-01-28T08:27:00.002+08:00

去年年底終於幫公司的專案升級成 Spring Boot，下一個 wish list 就是把一些討厭的邏輯轉成 AOP 的方式插入，然後就可以去除掉一些討厭的關聯了。不過因為自己實際上還沒有真的玩過 AOP，所以這篇就紀錄一點基本的東西。

AOP

AOP 的主要概念就是橫向切入，或者換句話說是用外掛的方式，把本來不屬於程式碼的邏輯 “外掛” 到程式碼當中。這種作法最主要的優點就是，外掛上去的邏輯可以放在別的地方，不會直接跟主邏輯綁在一起，因此也不會影響到主邏輯自身的程式碼。舉例來說，原本的程式碼可能是 A -> B.method()，表示 class A 的某一行去呼叫 class B 的 method() 方法。套上 AOP 時，在編譯期間，程式碼的呼叫會被編譯成 A -> aop.method() -> B.method()，也就是說 A 跟 B 的呼叫過程被額外加入了 AOP 的邏輯。

外掛是怎麼做到的，就我目前的理解是有兩種作法，一種是直接用 code generation 的方式，在程式碼編譯期間把外掛的程式碼包進去。所以雖然原始碼中是寫 A 呼叫 B，但編譯後產生的中繼碼，實際上寫的是 A 呼叫 AOP、然後 AOP 呼叫 B。第二種作法是 runtime proxy，就是透過 reflection 的方式把 aop 掛到 A 和 B 之間。兩種作法的目的是一樣的，但第一種作法顯然執行效率會比較高，因為第二種作法是執行期間才動態做 proxy。依據 Spring AOP 的文件，第一種作法是在 Spring AOP 裡直接使用 AspectJ 的話，AspectJ 會使用的作法；而第二種作法則是 Spring AOP 預設採取的作法。

Spring AOP

Spring AOP 算是簡易版的 AspectJ，功能比較受限，例如 Spring AOP 只能做 method 的攔截，其他 field 攔截等等的是不支援的。詳細的說明可以參考 Spring AOP Capabilities and Goals。

不過整體來說，最重要的一件事是，Spring AOP 只能夠對 Spring 管理的 bean 做攔截，這點很重要～。所以如果發現 AOP 一直沒發生效果，第一個先確認想要攔截的對象是不是被 Spring 管理的 bean。

Spring AOP 簡易範例

題外話，話說我在實驗時，有先叫 ChatGPT 產生範例程式碼給我，但結果它產生的程式碼其實有不少細節是錯的….。看起來 ChatGPT 把 Spring AOP 跟 AspectJ 混在一起使用的樣子…。

回歸正題 XD。這裡用一個很簡單的範例先展示 Spring AOP 的用法。首先需要引入 AOP 相關的 dependency，在 Spring Boot 可以簡單地放入 spring-boot-starter-aop 就好。

implementation("org.springframework.boot:spring-boot-starter-aop")

這個範例裡，我建立了一個 CommandLineRunner，作為 Spring Boot 的啟動對象。這個 Runner 裡面會隨機產生 10 個 Event，然後將 Event 餵給 FakeEventProcessor，所以我最後要被 AOP 插入的對象是 FakeEventProcessor。需要注意的是，這裡 FakeEventProcessor 是用注入的方式產生的，而不是自己呼叫 new，因為上面提到了 Spring AOP 只能對 Spring 管理的 bean 發生效用。

@Slf4j
@Component
public class Run implements CommandLineRunner {
    @Autowired
    private FakeEventProcessor processor;

    @Override
    public void run(String... args) throws Exception {
        int loop = 10;
        while(loop-- > 0) {
            var event = generateRandomEvent();
            processor.receiveEvent(event);
        }
    }
}

@Builder
@Getter
@Accessors(fluent = true)
@ToString
public class Event {
    private String eventType;
    private String owner;
}

@Slf4j
@Component
public class FakeEventProcessor {
    public void receiveEvent(Event event) {
        log.info("Receive: {}", event);
    }
}

接著宣告一個 Aspect，目的是我想要攔截 FakeEventProcessor 每次呼叫 receiveEvent() 的時候，都在它被呼叫前先呼叫我要插入的邏輯。

@Slf4j
@Aspect
@Component
public class TelemetryAspect {

    public TelemetryAspect() {
        log.info("Initiate aspect...");
    }

    @Before("execution(* tw.jimwayneyeh.example.otel.FakeEventProcessor.receiveEvent(..))")
    public void before(JoinPoint joinPoint) {
        Event event = (Event) joinPoint.getArgs()[0];
        log.trace("join '{}()': {}", joinPoint.getSignature().getName(), event);
    }
}

這裡我使用的攔截方式是 @Before，表示在目標被執行前先執行攔截的邏輯，並且攔截的對象是 @Before 裡定義的 method tw.jimwayneyeh.example.otel.FakeEventProcessor.receiveEvent(..)。而攔截後，我要拿出傳入的 event 並且印出 log，這樣我才能確認它攔截到的是什麼東西。

最後這段程式碼跑起來，會跑出以下的結果：

TRACE t.j.e.o.TelemetryAspect [main] join 'receiveEvent()': Event(eventType=delete, owner=owner-0)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=delete, owner=owner-0)
TRACE t.j.e.o.TelemetryAspect [main] join 'receiveEvent()': Event(eventType=update, owner=owner-1)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-1)
TRACE t.j.e.o.TelemetryAspect [main] join 'receiveEvent()': Event(eventType=update, owner=owner-6)
INFO  t.j.e.o.FakeEventProcessor [main] Receive: Event(eventType=update, owner=owner-6)
...(ignored)

這裡只列了最開始三行，因為後面都差不多 XD。可以看到針對每個 event 的呼叫，攔截的 log 會先出現（join 開頭的 log），然後才出現原本 method 執行的寫 log（Receive 開頭的 log），並且兩個 log 印出來的 event 是完全一樣的，表示 Aspect 確實被插入到 method call 之前了。

Spring Boot 啟用 mTLS

2022-11-10T23:28:00.002+08:00

最近在幫專案導入 Spring Boot，導入時比較麻煩的地方，是要保持專案的權限控制，也就是要讓它依然能夠正常以 Mutual TLS 的方式進行驗證。雖然在這個狀況下，往好處想是我們已經有現成的測試程序，能夠用來驗證是否 Mutual TLS 有正常運作，不過當驗證異常的時候，要找出問題還是蠻費工夫的…。這篇會稍微紀錄一點相關的資訊。

什麼是 Mutual TLS？

Mutual TLS（或者簡稱 mTLS）是驗證範圍更寬一點的 HTTPS，一般討論 HTTPS 時，比較常見的討論對象是單向的 TLS，也就是讓客戶端驗證伺服器是否真的是它宣稱的伺服器。而 Mutual TLS 則是雙向的 TLS，不但客戶端要驗證伺服器、伺服器也要驗證客戶端。換句話說，伺服器和客戶端都需要有私鑰和憑證。

TLS 相關名詞解釋

TLS 在運作時，會需要有公鑰（public key）和私鑰（private key），這裡就不解釋各自的用途了。實際 TLS 在運作時，通常會以私鑰和憑證（certificate）的形式在表示，其中憑證的內容是包含了公鑰、發行者（Issuer）和有效時間等資訊的檔案。也就是說，憑證會拿來提供給對方做驗證。

在使用 curl 時，會注意到 curl 允許的 --key 和 --cert 的格式是 PEM，這是因為 curl 就只支援 PEM 格式。不過在 Java 的世界中，比較麻煩的是 Java 一般不支援 PEM，所以網路上的文章常常會看到有使用 keytool 的流程，這個流程是為了把 PEM 格式的私鑰和憑證，轉換成 PKCS #12（.p12）或者 Java KeyStore 格式（.jks）的檔案。可以參考公鑰密碼學標準。

除了 KeyStore 以外，另外還會有個 TrustStore 的玩意兒。兩個的功能剛好相反，KeyStore 是用來讓別人做驗證、TrustStore 的功能則是用來驗證別人。所以說，KeyStore 的產生會使用自己的私鑰和憑證，這是因為產生出來的 KeyStore 內容也會包含自己的憑證資訊。

設定 Spring Boot 的 SSL

具體設定方法，可以參考官方文件中 How-to 章節的 SSL 部份。不過我個人其實覺得官方文件寫得還挺籠統的…。

實際我自己在設定時，在 Spring Boot + Jetty 底下有遇到幾種奇怪的狀況：

使用 keystore（JKS）和 truststore，然後 Spring Boot 顯示有正常啟動 HTTPS，但結果用 curl 或 openssl 檢查時，都檢查不到有 HTTPS。
使用 PEM，然後 HTTPS 正常啟動，憑證也能正常被客戶端讀取，但 mTLS 一直失敗。

最後這裡直接紀錄目前會成功的版本，是採用 PKCS12 的格式讓 Spring Boot 讀取。

server.port=8443
server.ssl.enabled=true
server.ssl.key-store=/path/to/key/store/my_keystore.p12  # PKCS12 檔案的路徑
server.ssl.key-alias=accio  # 別名，在產生 PKCS12 檔的時候指定的名字
server.ssl.key-store-password=mypassword  # PKCS12 的密碼
server.ssl.trust-store=/path/to/trust/store/my_truststore.jks  # trust store 檔案的路徑
server.ssl.trust-store-type=JCEKS  # trust store 檔案的格式
server.ssl.trust-store-password=mypassword  # trust store 的密碼
server.ssl.client-auth=want  # 啟用 mTLS，但不強制

如何檢查 HTTPS？

使用 curl 或者 openssl 都可以做檢查 HTTPS。

openssl

用 openssl 時，就是讓 openssl 模擬成 client，指令如下：

openssl s_client -connect localhost:8443

以我的狀況，如果 HTTPS 啟動但有問題 (?) 的話，會出現以下這樣的訊息。

[root@a976d6ac5637 ~]# openssl s_client -connect localhost:8443
CONNECTED(00000003)
140387372447632:error:14077410:SSL routines:SSL23_GET_SERVER_HELLO:sslv3 alert handshake failure:s23_clnt.c:769:
---
no peer certificate available
---
No client certificate CA names sent
---
SSL handshake has read 7 bytes and written 289 bytes
---
New, (NONE), Cipher is (NONE)
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : TLSv1.2
    Cipher    : 0000
    Session-ID:
    Session-ID-ctx:
    Master-Key:
    Key-Arg   : None
    Krb5 Principal: None
    PSK identity: None
    PSK identity hint: None
    Start Time: 1667406122
    Timeout   : 300 (sec)
    Verify return code: 0 (ok)
---

訊息中可以明確看出，openssl 並沒有找到合適的 cipher 能夠進行加密連線。

而如果是正常的 HTTPS 的話，會像是這樣：

[root@a976d6ac5637 ~]# openssl s_client -connect google.com:443
CONNECTED(00000005)
depth=3 C = BE, O = GlobalSign nv-sa, OU = Root CA, CN = GlobalSign Root CA
verify return:1
depth=2 C = US, O = Google Trust Services LLC, CN = GTS Root R1
verify return:1
depth=1 C = US, O = Google Trust Services LLC, CN = GTS CA 1C3
verify return:1
depth=0 CN = *.google.com
verify return:1
---
Certificate chain
 0 s:/CN=*.google.com
   i:/C=US/O=Google Trust Services LLC/CN=GTS CA 1C3
 1 s:/C=US/O=Google Trust Services LLC/CN=GTS CA 1C3
   i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
 2 s:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
   i:/C=BE/O=GlobalSign nv-sa/OU=Root CA/CN=GlobalSign Root CA
---
Server certificate
-----BEGIN CERTIFICATE-----
....(ignored)....
-----END CERTIFICATE-----
subject=/CN=*.google.com
issuer=/C=US/O=Google Trust Services LLC/CN=GTS CA 1C3
---
No client certificate CA names sent
Server Temp Key: ECDH, X25519, 253 bits
---
SSL handshake has read 7270 bytes and written 281 bytes
---
New, TLSv1/SSLv3, Cipher is ECDHE-RSA-CHACHA20-POLY1305
Server public key is 2048 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : TLSv1.2
    Cipher    : ECDHE-RSA-CHACHA20-POLY1305
    Session-ID: D0F1CB0DAE17297143F933D8C93BB905D088849CAAFED06698803C8F14367771
    Session-ID-ctx:
    Master-Key: ADC789FEFEF3A3747E6741D23B090CAA3E1BBEB8B6DED6EB44910E45257F9C977378CCAB42C387828EDC2CC8D4B91059
    TLS session ticket lifetime hint: 100800 (seconds)
    TLS session ticket:
    ....(ignored)....

    Start Time: 1668083091
    Timeout   : 7200 (sec)
    Verify return code: 0 (ok)
---

部分細節我就直接刪掉了，不過可以看出正常狀況它應該要能解析出 server 的憑證內容，並且顯示使用什麼協定來跟伺服器溝通。

附錄：Jetty 的 log

由於我用的是 Jetty，因此如果想追 Jetty 這邊的 log，可以打開 org.eclipse.jetty 的 debug log，從訊息中可以看出，Jetty 在啟用 HTTPS 時，會建立 SslContextFactory 的物件來進行（廢話）。更具體來說，應該會是 SslContextFactory.Server 物件。雖然說，出現這段看起來有啟動 HTTPS 的 log，實際上並不代表 HTTPS 就有正常被啟動了。我的實驗過程有遇到一個情況是 log 顯示 HTTPS 似乎啟動了，但結果真的用 curl 跟 openssl 打都找不到憑證…。

2022-11-02 15:48:15,603 [main] DEBUG org.eclipse.jetty.util.component.AbstractLifeCycle - starting SslConnectionFactory@40ee0a22{SSL->HTTP/1.1}
2022-11-02 15:48:15,603 [main] DEBUG org.eclipse.jetty.util.component.AbstractLifeCycle - starting Server@7bde1f3a[provider=null,keyStore=file:////path/to/key/store/my_keystore.p12,trustStore=file:////path/to/trust/store/my_truststore.jks]
2022-11-02 15:48:15,636 [main] DEBUG org.eclipse.jetty.util.ssl.SslContextFactory - managers=[org.eclipse.jetty.util.ssl.AliasedX509ExtendedKeyManager@5cc152f9] for Server@7bde1f3a[provider=null,keyStore=file:////path/to/key/store/my_keystore.p12,trustStore=file:////path/to/trust/store/my_truststore.jks]
2022-11-02 15:48:15,640 [main] DEBUG org.eclipse.jetty.util.ssl.SslContextFactory - Selected Protocols [TLSv1.3, TLSv1.2] of [TLSv1.3, TLSv1.2, TLSv1.1, TLSv1, SSLv3, SSLv2Hello]
2022-11-02 15:48:15,640 [main] DEBUG org.eclipse.jetty.util.ssl.SslContextFactory - Selected Ciphers   [TLS_AES_256_GCM_SHA384, ....]
2022-11-02 15:48:15,640 [main] DEBUG org.eclipse.jetty.util.ssl.SslContextFactory - Customize sun.security.ssl.SSLEngineImpl@1117cc7c
2022-11-02 15:48:15,641 [main] DEBUG org.eclipse.jetty.util.component.AbstractLifeCycle - STARTED @119497ms Server@7bde1f3a[provider=null,keyStore=file:////path/to/key/store/my_keystore.p12,trustStore=file:////path/to/trust/store/my_truststore.jks]
2022-11-02 15:48:15,641 [main] DEBUG org.eclipse.jetty.util.ssl.SslContextFactory - Customize sun.security.ssl.SSLEngineImpl@4797023d
2022-11-02 15:48:15,641 [main] DEBUG org.eclipse.jetty.util.component.AbstractLifeCycle - STARTED @119497ms SslConnectionFactory@40ee0a22{SSL->HTTP/1.1}

Markdown Here 樣式筆記

2022-10-23T22:20:00.006+08:00

紀錄目前 Markdown Here plugin 使用的設定。

Syntax Highlight 模板：Monokai Sublime

CSS：
這裡主要是模板以外再複寫一次 blockquote 的語法，讓部落格本來就在用的 blockquote 樣式維持原狀。

/*
 * NOTE:
 * - The use of browser-specific styles (-moz-, -webkit-) should be avoided.
 *   If used, they may not render correctly for people reading the email in
 *   a different browser than the one from which the email was sent.
 * - The use of state-dependent styles (like a:hover) don't work because they
 *   don't match at the time the styles are made explicit. (In email, styles
 *   must be explicitly applied to all elements -- stylesheets get stripped.)
 */

/* This is the overall wrapper, it should be treated as the `body` section. */
.markdown-here-wrapper {
}

/* To add site specific rules, you can use the `data-md-url` attribute that we
   add to the wrapper element. Note that rules like this are used depending
   on the URL you're *sending* from, not the URL where the recipient views it.
*/
/* .markdown-here-wrapper[data-md-url*="mail.yahoo."] ul { color: red; } */

pre, code {
  font-size: 0.85em;
  font-family: Consolas, Inconsolata, Courier, monospace;
}

code {
  margin: 0 0.15em;
  padding: 0 0.3em;
  white-space: pre-wrap;
  border: 1px solid #EAEAEA;
  background-color: #F8F8F8;
  border-radius: 3px;
  display: inline; /* added to fix Yahoo block display of inline code */
}

pre {
  font-size: 1em;
  line-height: 1.2em;
}

pre code {
  white-space: pre;
  overflow: auto; /* fixes issue #70: Firefox/Thunderbird: Code blocks with horizontal scroll would have bad background colour */
  border-radius: 3px;
  border: 1px solid #CCC;
  padding: 0.5em 0.7em;
  display: block !important; /* added to counteract the Yahoo-specific `code` rule; without this, code blocks in Blogger are broken */
}

/* In edit mode, Wordpress uses a `* { font: ...;} rule+style that makes highlighted
code look non-monospace. This rule will override it. */
.markdown-here-wrapper[data-md-url*="wordpress."] code span {
  font: inherit;
}

/* Wordpress adds a grey background to `pre` elements that doesn't go well with
our syntax highlighting. */
.markdown-here-wrapper[data-md-url*="wordpress."] pre {
  background-color: transparent;
}

/* This spacing has been tweaked to closely match Gmail+Chrome "paragraph" (two line breaks) spacing.
Note that we only use a top margin and not a bottom margin -- this prevents the
"blank line" look at the top of the email (issue #243).
*/
p {
  /* !important is needed here because Hotmail/Outlook.com uses !important to
     kill the margin in <p>. We need this to win. */
  margin: 0 0 1.2em 0 !important;
}

table, pre, dl, blockquote, q, ul, ol {
  margin: 1.2em 0;
}

ul, ol {
  padding-left: 2em;
}

li {
  margin: 0.5em 0;
}

/* Space paragraphs in a list the same as the list itself. */
li p {
  /* Needs !important to override rule above. */
  margin: 0.5em 0 !important;
}

/* Smaller spacing for sub-lists */
ul ul, ul ol, ol ul, ol ol {
  margin: 0;
  padding-left: 1em;
}

/* Use Roman numerals for sub-ordered-lists. (Like Github.) */
ol ol, ul ol {
  list-style-type: lower-roman;
}

/* Use letters for sub-sub-ordered lists. (Like Github.) */
ul ul ol, ul ol ol, ol ul ol, ol ol ol {
  list-style-type: lower-alpha;
}

dl {
  padding: 0;
}

dl dt {
  font-size: 1em;
  font-weight: bold;
  font-style: italic;
}

dl dd {
  margin: 0 0 1em;
  padding: 0 1em;
}

blockquote, q {
  border-left: 4px solid #DDD;
  padding: 0 1em;
  color: #777;
  quotes: none;
}

blockquote::before, blockquote::after, q::before, q::after {
  content: none;
}

blockquote{border-left: 15px solid #c76c0c;font-family: Georgia, serif;font-size:15px;text-align: justify;background: #fff;line-height: 1.2;
display:block;margin: 0 0 20px;padding: 15px 20px 15px 45px;position: relative; font-size: 16px;color: #666;
border-right: 2px solid #c76c0c;box-shadow: 2px 2px 15px #ccc;-webkit-box-shadow: 2px 2px 15px #ccc;-moz-box-shadow: 2px 2px 15px #ccc;}
blockquote::before{font-size: 50px;position: absolute;color: #999;left: 10px;top:5px;font-weight: bold;content: "\201C";}
blockquote a{cursor: pointer;color: #c76c0c;text-decoration: none;background: #eee;padding: 0 3px;}
blockquote a:hover{color: #555;}

h1, h2, h3, h4, h5, h6 {
  margin: 1.3em 0 1em;
  padding: 0;
  font-weight: bold;
}

h1 {
  font-size: 1.6em;
  border-bottom: 1px solid #ddd;
}

h2 {
  font-size: 1.4em;
  border-bottom: 1px solid #eee;
}

h3 {
  font-size: 1.3em;
}

h4 {
  font-size: 1.2em;
}

h5 {
  font-size: 1em;
}

h6 {
  font-size: 1em;
  color: #777;
}

table {
  padding: 0;
  border-collapse: collapse;
  border-spacing: 0;
  font-size: 1em;
  font: inherit;
  border: 0;
}

tbody {
  margin: 0;
  padding: 0;
  border: 0;
}

table tr {
  border: 0;
  border-top: 1px solid #CCC;
  background-color: white;
  margin: 0;
  padding: 0;
}

table tr:nth-child(2n) {
  background-color: #F8F8F8;
}

table tr th, table tr td {
  font-size: 1em;
  border: 1px solid #CCC;
  margin: 0;
  padding: 0.5em 1em;
}

table tr th {
 font-weight: bold;
  background-color: #F0F0F0;
}

[筆記] 詞彙的建立

2022-09-04T23:51:00.007+08:00

在 IR 系統的前處理中，因為我們想要把資料建成 posting list，會需要先有相關的詞彙，才有辦法依據詞彙建立相應的 posting list。不過這時會有幾個常見的問題需要處理。

這篇會簡要紀錄一下書中提到的考量點。

1. Tokenization

Tokenization 是把句子分割並萃取的技術，萃取出來的單位被稱為 token，或者也可能被稱為 word、term，但事實上有時候我們可能會想要把 token 跟其他名詞做一點定義上的區分。以下是書中對於 token 的定義：

A token is an instance of a sequence of characters in some particular document that are grouped together as a useful semantic unit for processing.

除了 token 以外，另外還有 type 和 term 這兩個名詞。書中提供的定義分別如下：

A type is the class of all tokens containing the same character sequence.

A term is a (perhaps normalized) type that is included in the IR system’s dictionary.

直接用書中提供的例子應該會比較好懂。舉例來說，如果我們想對下述的句子做 tokenization：

to sleep perchance to dream

此時，會有 to, sleep, perchance, to, dream 共 5 個 token；但只會有 4 個 type：to, sleep, perchance, dream，因為有兩個 to 是重複的；而如果 IR 系統中有處理 stop words，我們可能會把 to 視為是 stop words 而將它移除，此時最終在 IR 系統中被 index 的 term 就只會有 3 個：sleep, perchance, dream 。

那麼我們通常會如何做 tokenziation 呢？初步看起來，似乎就是直接針對空白做分割，然後可能把標點符號什麼的都去除掉就可以了？然而現實上，還是會出現一些比較困難的問題，導致我們可能還需要考慮別的因子。例如：

' 在英文中，可以代表所有格關係、也可以代表縮寫。
不同語言有自己的語言特徵。
特定領域可能有自己特殊的 type。
- 在英文中也存在多種不同用法。
多個字組成的詞彙無法單純用空白切割來處理。

以下會分別針對這些狀況做點簡單的描述。

1.1. Apostrophe (‘)

' 這個符號在英文中有多種用法，例如以下這個句子：

Mr. O'Neill thinks that the boys' stories about Chile's capital aren't amusing.

這裡同時出現了三種不同的用法：

O’Neill 中的 ' 是名字的一部分。
boys’ 和 Chile’s 中的 ' 是所有格。
aren’t 中的 ' 是縮寫。

此時針對 ' 做的處理的不同，可能會導致後續 IR 系統的 matching 受到影響。例如如果我們將 ' 拆開的話，aren't 被拆成 aren 跟 t 看起來就會很奇怪。同時，O'Neill 被拆成 O 跟 Neill 會導致搜尋時使用 o'neil 會無法 match 到相應的 token。

1.2. 語言特徵

tokenization 的行為往往跟語言有很大的關係，不同語言的 tokenization 作法會有蠻大的不同。例如中文和日文就沒有空白分隔的特性，每個字都是連在一起的。

1.3. 領域特徵

在特定領域，有可能有領域內專屬的詞彙需要能夠被識別成 term，例如 C++ 和 C#、或者飛機型號 B-52（戰略轟炸機）。另外網際網路中的 URL（https://xxx）、e-mail（abc@abc.com）、IP 位址（a.b.c.d）等等可能也會需要能夠被視為是獨立的 term。

1.4. 連字符號 Hyphenation (-)

英文中連字符號的處理可能會很複雜，書中舉出幾種連字符號的用法：

分隔單字之間的母音，像是 co-education。這個例子實際上它代表的是 coeducaion。
將多個名詞連接成一個新的名稱，例如 Hewlett-Packard。
多個詞語的組成結果，例如 the hold-him-back-and-drag-him-away maneuver。這個例子應該要被拆解成各自獨立的 term。

1.5. 特殊詞彙

這類的資訊其實我覺得也可以算是領域特徵的一種。例如書中舉的一個例子是 New York University（紐約大學）跟 York University（約克大學）。如果他們沒有被獨立視為 term，而是純粹依據空白拆開的話，那麼搜尋 York University 時就會 match 到 New York University 了，但這顯然並非是使用者想找的東西。

2. Stop Words

停用詞（Stop Words）的目的，是去除出現頻率過高、但又跟文件本身關係不大的詞彙。不過由於去除停用詞的行為，有時會導致意義的流失，所以現代的 IR 系統比較會考慮不去除停用詞，改為將停用詞賦予較低的權重，使其影響變小。舉例來說，flights to London 如果把 to 給去除了，flights to London 的意義就流失了。

其實還有兩個小節，不過等有空時再補筆記了…。
是說搜尋是個在現代非常常見的行為，但最近的研究總覺得這個領域有點冷門？